Create timeline or timeline template

edit

Creates a new timeline or timeline template.

Use the timeline object’s timelineType field to determine whether a timeline or a timeline template is created, where:

  • default creates a new timeline ("timelineType": "default")
  • template creates a new timeline template ("timelineType": "template")

If you do not specify the timelineType field, a new timeline is created.

Request URL

edit

POST <kibana host>:<port>/api/timeline

Request body

edit

A JSON object defining the timeline or timeline template query and time filter.

For detailed information about the Timeline object schema and its corresponding UI components, see Timeline schema.

Name Type Description Required

timeline

timeline

The timeline object, which defines the search criteria and time range. The only required field is title.

When you are creating a timeline template, provide these fields to so you can easily import template updates:

  • templateTimelineId: Unique identifier (UUID, for timeline templates only)
  • templateTimelineVersion: Template version number (for timeline templates only)

Yes

timelineId

String

If provided, must be null for a new timeline or template.

No

version

String

If provided, must be null for a new timeline or template.

No

Example requests

edit

Example 1

Creates a new timeline:

POST api/timeline
{
  "timeline": {
    "columns": [
      {
        "id": "@timestamp"
      },
      {
        "id": "user.name"
      },
      {
        "id": "event.category"
      },
      {
        "id": "event.action"
      },
      {
        "id": "host.name"
      }
    ],
    "dataProviders": [ 
      {
        "and": [
          {
            "name": "event.category",
            "enabled": true,
            "excluded": false,
            "queryMatch": {
              "field": "event.category",
              "value": "process",
              "operator": ":"
            }
          },
          {
            "name": "user.name",
            "enabled": true,
            "excluded": false,
            "queryMatch": {
              "field": "user.name",
              "value": "SYSTEM",
              "operator": ":"
            }
          }
        ],
        "enabled": true,
        "excluded": false,
        "name": "host.os.platform",
        "queryMatch": {
          "field": "host.os.platform",
          "value": "windows",
          "operator": ":"
        }
      }
    ],
    "dateRange": {
      "end": 1594005719000,
      "start": 1593832919000
    },
    "description": "Gets Windows system processes from all hosts",
    "title": "Windows system processes"
  }
}

To ensure the timeline is displayed correctly in the UI, specify these fields in all dataProviders objects:

  • and (can be empty)
  • name
  • enabled
  • excluded
  • queryMatch

    • field
    • value
    • operator

Example 2

Creates a new timeline template:

POST api/timeline
{
  "timeline": {
    "columns": [
      {
        "id": "@timestamp"
      },
      {
        "id": "user.name"
      },
      {
        "id": "event.category"
      },
      {
        "id": "event.action"
      },
      {
        "id": "host.name"
      }
    ],
    "dataProviders": [
      {
        "and": [
          {
            "name": "event.category",
            "enabled": true,
            "excluded": false,
            "queryMatch": {
              "field": "event.category",
              "operator": ":",
              "value": "process" 
            }
          },
          {
            "name": "user.name",
            "enabled": true,
            "excluded": false,
            "queryMatch": {
              "field": "user.name",
              "operator": ":",
              "value": "SYSTEM"
            }
          }
        ],
        "enabled": true,
        "excluded": false,
        "name": "host.os.platform",
        "queryMatch": {
          "field": "host.os.platform",
          "operator": ":",
          "value": "windows"
        }
      }
    ],
    "dateRange": {
      "end": 1594005719000,
      "start": 1593832919000
    },
    "description": "Template for investigating host events",
    "templateTimelineId": "6acb2c90-a01c-11ea-8e47-5dc21077d10c", 
    "templateTimelineVersion": 1, 
    "timelineType": "template", 
    "title": "Host event template"
  }
}

To ensure the timeline template is displayed correctly in the UI, specify the value field even though it is replaced when alerts are investigated in Timeline.

Template UUID.

Template version number.

To create templates, the timelineType field value must be template.

Example 3

Creates the a timeline template that uses the kqlQuery object (KQL bar in the UI) to ensure only Windows alerts are displayed when alerts are investigated in Timeline:

POST api/timeline
{
  "timeline": {
    "columns": [
      {
        "id": "@timestamp"
      },
      {
        "id": "user.name"
      },
      {
        "id": "event.category"
      },
      {
        "id": "event.action"
      },
      {
        "id": "host.name"
      }
    ],
    "dataProviders": [
      {
        "and": [
          {
            "enabled": true,
            "excluded": false,
            "name": "user.name",
            "queryMatch": {
              "field": "user.name",
              "operator": ":",
              "value": "SYSTEM"
            }
          }
        ],
        "enabled": true,
        "excluded": false,
        "name": "event.category",
        "queryMatch": {
          "field": "event.category",
          "operator": ":",
          "value": "process"
        }
      }
    ],
    "dateRange": {
      "end": 1594005719000,
      "start": 1593832919000
    },
    "description": "Template for investigating Windows events",
    "kqlMode": "filter",
    "kqlQuery": {
      "filterQuery": {
        "kuery": {
          "expression": "host.os.platform : windows",
          "kind": "kuery"
        }
      }
    },
    "templateTimelineId": "6f9a3480-bf4f-11ea-9fcd-ed4e5fd0dcd1",
    "templateTimelineVersion": 1,
    "timelineType": "template",
    "title": "Windows event template"
  }
}

Response code

edit
200
Indicates a successful call.

Response payload

edit

A JSON timeline object with a unique savedObjectId and its version.

Example 1

Timeline response payload:

{
  "data": {
    "persistTimeline": {
      "code": 200,
      "message": "success",
      "timeline": {
        "savedObjectId": "7f069820-bf57-11ea-9fcd-ed4e5fd0dcd1",
        "version": "WzQwMiwxXQ==",
        "columns": [
          {
            "id": "@timestamp"
          },
          {
            "id": "user.name"
          },
          {
            "id": "event.category"
          },
          {
            "id": "event.action"
          },
          {
            "id": "host.name"
          }
        ],
        "dataProviders": [
          {
            "and": [
              {
                "name": "event.category",
                "enabled": true,
                "excluded": false,
                "queryMatch": {
                  "field": "event.category",
                  "value": "process",
                  "operator": ":"
                }
              },
              {
                "name": "user.name",
                "enabled": true,
                "excluded": false,
                "queryMatch": {
                  "field": "user.name",
                  "value": "SYSTEM",
                  "operator": ":"
                }
              }
            ],
            "enabled": true,
            "excluded": false,
            "name": "host.os.platform",
            "queryMatch": {
              "field": "host.os.platform",
              "value": "windows",
              "operator": ":"
            }
          }
        ],
        "dateRange": {
          "end": 1594005719000,
          "start": 1593832919000
        },
        "description": "Gets Windows system processes from all hosts",
        "title": "Windows system processes",
        "created": 1594019310069,
        "createdBy": "LiverpoolFC",
        "updated": 1594019310069,
        "updatedBy": "LiverpoolFC",
        "timelineType": "default",
        "status": "active"
      }
    }
  }
}

Example 2

Timeline template response payload:

{
  "data": {
    "persistTimeline": {
      "code": 200,
      "message": "success",
      "timeline": {
        "savedObjectId": "75b6cf30-bf82-11ea-9fcd-ed4e5fd0dcd1",
        "version": "WzQ4MiwxXQ==",
        "columns": [
          {
            "id": "@timestamp"
          },
          {
            "id": "user.name"
          },
          {
            "id": "event.category"
          },
          {
            "id": "event.action"
          },
          {
            "id": "host.name"
          }
        ],
        "dataProviders": [
          {
            "and": [
              {
                "enabled": true,
                "excluded": false,
                "name": "user.name",
                "queryMatch": {
                  "field": "user.name",
                  "operator": ":",
                  "value": "SYSTEM"
                }
              }
            ],
            "enabled": true,
            "excluded": false,
            "name": "event.category",
            "queryMatch": {
              "field": "event.category",
              "operator": ":",
              "value": "process"
            }
          }
        ],
        "dateRange": {
          "end": 1594005719000,
          "start": 1593832919000
        },
        "description": "Template for investigating Windows events",
        "kqlMode": "filter",
        "kqlQuery": {
          "filterQuery": {
            "kuery": {
              "expression": "host.os.platform : windows",
              "kind": "kuery"
            }
          }
        },
        "templateTimelineId": "6f9a3480-bf4f-11ea-9fcd-ed4e5fd0dcd1",
        "templateTimelineVersion": 1,
        "timelineType": "template",
        "title": "Windows event template",
        "created": 1594037762797,
        "createdBy": "LiverpoolFC",
        "updated": 1594037762797,
        "updatedBy": "LiverpoolFC",
        "status": "active"
      }
    }
  }
}