Timeline schema

edit

The Timeline schema lists all the JSON fields and objects required to create a Timeline or a Timeline template using the Create timeline API.

All column, dropzone, and filter fields must be ECS fields.

This screenshot maps the Timeline UI components to their JSON objects:

timeline object ui
  1. Title (title)
  2. Description (description)
  3. Global notes (globalNotes)
  4. Time filter (dateRange)
  5. Dropzone (each clause is contained in its own dataProviders object)
  6. KQL bar mode (kqlMode)
  7. KQL bar query (kqlQuery)
  8. Event types included in Timeline results (eventType)
  9. Additional filters (filters)
  10. Column headers (columns)
  11. Event-specific notes (eventNotes)
Name Type Description

columns

columns[]

The timeline’s columns.

created

Float

The time the timeline was created, using a 13-digit Epoch timestamp.

createdBy

String

The user who created the timeline.

dataProviders

dataProviders[]

Object containing dropzone query clauses.

dateRange

dateRange

The timeline’s search period:

  • end: The time up to which events are searched, using a 13-digit Epoch timestamp.
  • start: The time from which events are searched, using a 13-digit Epoch timestamp.

description

String

The timeline’s description.

eventNotes

eventNotes[]

Notes added to specific events in the timeline.

eventType

String

Event types displayed in the timeline, which can be:

  • All data sources
  • Events: Event sources only
  • Detection Alerts: Detection alerts only

favorite

favorite[]

Indicates when and who marked a timeline as a favorite.

filters

filters[]

Filters used in addition to the dropzone query.

globalNotes

globalNotes[]

Global notes added to the timeline.

kqlMode

String

Indicates whether the KQL bar filters the dropzone query results or searches for additional results, where:

  • filter: filters dropzone query results
  • search: displays additional search results

kqlQuery

kqlQuery

KQL bar query.

pinnedEventIds

pinnedEventIds[]

IDs of events pinned to the timeline’s search results.

savedObjectId

String

The timeline’s saved object ID.

savedQueryId

String

If used, the saved query ID used to filter or search dropzone query results.

sort

sort

Object indicating how rows are sorted in the timeline’s grid:

  • columnId (string): The ID of the column used to sort results.
  • sortDirection (string): The sort direction, which can be either desc or asc.

templateTimelineId

String

A unique ID (UUID) for Timeline templates. For timelines, the value is null.

templateTimelineVersion

Integer

Timeline template version number. For timelines, the value is null.

timelineType

String

Indicates whether the timeline is a template or not, where:

  • default: Indicates a timeline used to actively investigate events.
  • template: Indicates a timeline template used when detection rule alerts are investigated in Timeline.

title

String

The timeline’s title.

updated

Float

The last time the timeline was updated, using a 13-digit Epoch timestamp.

updatedBy

String

The user who last updated the timeline.

version

String

The timeline’s version.

columns object

edit
Name Type Description

aggregatable

Boolean

Indicates whether the field can be aggregated across all indices (used to sort columns in the UI).

category

String

The ECS field set to which the field belongs.

description

String

UI column field description tooltip.

example

String

UI column field example tooltip.

indexes

String

Security indices in which the field exists and has the same Elasticsearch type. null when all the security indices have the field with the same type.

id

String

ECS field name, displayed as the column header in the UI.

type

String

The field’s type.

dataProviders object

edit
Name Type Description

and

dataProviders[]

Array containing dropzone query clauses using AND logic.

enabled

Boolean

Indicates if the dropzone query clause is enabled.

excluded

Boolean

Indicates if the dropzone query clause uses NOT logic.

id

String

The dropzone query clause’s unique ID.

name

String

The dropzone query clause’s name (the clause’s value when timelines are exported from the UI).

queryMatch

queryMatch

The dropzone query clause:

  • field (string): The field used to search Security indices.
  • operator (string): The clause’s operator, which can be:

    • : - The field has the specified value.
    • :* - The field exists.
  • value (string): The field’s value used to match results.

eventNotes object

edit
Name Type Description

created

Float

The time the note was created, using a 13-digit Epoch timestamp.

createdBy

String

The user who added the note.

eventId

String

The ID of the event to which the note was added.

note

String

The note’s text.

noteId

String

The note’s ID

timelineId

String

The ID of the timeline to which the note was added.

updated

Float

The last time the note was updated, using a 13-digit Epoch timestamp.

updatedBy

String

The user who last updated the note.

version

String

The note’s version.

favorite object

edit
Name Type Description

favoriteDate

Float

The time the timeline was marked as a favorite, using a 13-digit Epoch timestamp.

fullName

String

The full name of the user who marked the timeline as a favorite.

keySearch

String

userName encoded in Base64.

userName

String

The Kibana username of the user who marked the timeline as a favorite.

filters object

edit
Name Type Description

exists

String

Exists term query for the specified field (null when undefined). For example, {"field":"user.name"}.

meta

meta

Filter details:

  • alias (string): UI filter name.
  • disabled (boolean): Indicates if the filter is disabled.
  • key(string): Field name or unique string ID.
  • negate (boolean): Indicates if the filter query clause uses NOT logic.
  • params (string): Value of phrase filter types.
  • type (string): Type of filter. For example, exists and range. For more information about filtering, see Query DSL.

match_all

String

Match all term query for the specified field (null when undefined).

query

String

DSL query (null when undefined). For example, {"match_phrase":{"ecs.version":"1.4.0"}}.

range

String

Range query (null when undefined). For example, {"@timestamp":{"gte":"now-1d","lt":"now"}}".

globalNotes object

edit
Name Type Description

created

Float

The time the note was created, using a 13-digit Epoch timestamp.

createdBy

String

The user who added the note.

note

String

The note’s text.

noteId

String

The note’s ID

timelineId

String

The ID of the timeline to which the note was added.

updated

Float

The last time the note was updated, using a 13-digit Epoch timestamp.

updatedBy

String

The user who last updated the note.

version

String

The note’s version.

kqlQuery object

edit
Name Type Description

filterQuery

filterQuery

Object containing query details:

  • kuery: Object containing the query’s clauses and type:

    • expression(string): The query’s clauses.
    • kind (string): The type of query, which can be kuery or lucene.
  • serializedQuery (string): The query represented in JSON format.