---
type: api
title: Get Timelines or Timeline templates
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4268/api/doc/kibana/v8/operation/operation-gettimelines
resource: https://www.elastic.co/elastic/docs-builder/docs/4268/api/doc/kibana/v8/operation/operation-gettimelines
products:
  - Kibana
---

# Get Timelines or Timeline templates

Authentication: required

- Server: `https://{kibana_url}`

## Paths

- `GET` `/api/timelines`
- `GET` `/s/{space_id}/api/timelines`

#### Path parameters

- `space_id` (string) — optional
  An identifier for the space. If `space_id` is not provided in the URL, the default space is used. Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

## Description

Get a list of all saved Timelines or Timeline templates.

## Query string parameters

- `only_user_favorite` (enum) — optional — nullable
  If true, only timelines that are marked as favorites by the user are returned.
  Values: `true`, `false`
- `timeline_type` (enum) — optional
  Values: `default`, `template`
- `sort_field` (enum) — optional
  Values: `title`, `description`, `updated`, `created`
- `sort_order` (enum) — optional
  Whether to sort the results `ascending` or `descending`
  Values: `asc`, `desc`
- `page_size` (string) — optional — nullable
  How many results should returned at once
- `page_index` (string) — optional — nullable
  How many pages should be skipped
- `search` (string) — optional — nullable
  Allows to search for timelines by their title
- `status` (enum) — optional
  Values: `active`, `draft`, `immutable`

## Responses

#### `200`

Indicates that the (template) Timelines were found and returned.

`application/json`

- `customTemplateTimelineCount` (number)
  The amount of custom Timeline templates in the results
- `defaultTimelineCount` (number)
  The amount of `default` type Timelines in the results
- `elasticTemplateTimelineCount` (number)
  The amount of Elastic's Timeline templates in the results
- `favoriteCount` (number)
  The amount of favorited Timelines
- `templateTimelineCount` (number)
  The amount of Timeline templates in the results
- `timeline` (object[])
  - `columns` (object[]) — nullable
    The Timeline's columns
    - `aggregatable` (boolean) — nullable
    - `category` (string) — nullable
    - `columnHeaderType` (string) — nullable
    - `description` (string) — nullable
    - `example` (string) — nullable
    - `id` (string) — nullable
    - `indexes` (string[]) — nullable
    - `name` (string) — nullable
    - `placeholder` (string) — nullable
    - `searchable` (boolean) — nullable
    - `type` (string) — nullable
  - `created` (number) — nullable
    The time the Timeline was created, using a 13-digit Epoch timestamp.
  - `createdBy` (string) — nullable
    The user who created the Timeline.
  - `dataProviders` (object[]) — nullable
    Object containing query clauses
    - `and` (object[]) — nullable
      - `enabled` (boolean) — nullable
      - `excluded` (boolean) — nullable
      - `id` (string) — nullable
      - `kqlQuery` (string) — nullable
      - `name` (string) — nullable
      - `queryMatch` (object)
        - `displayField` (string) — nullable
        - `displayValue` (string) — nullable
        - `field` (string) — nullable
        - `operator` (string) — nullable
        - `value` (union string | string[]) — nullable
      - `type` (enum)
        The type of data provider.
        Values: `default`, `template`
    - `enabled` (boolean) — nullable
    - `excluded` (boolean) — nullable
    - `id` (string) — nullable
    - `kqlQuery` (string) — nullable
    - `name` (string) — nullable
    - `queryMatch` (object)
      - `displayField` (string) — nullable
      - `displayValue` (string) — nullable
      - `field` (string) — nullable
      - `operator` (string) — nullable
      - `value` (union string | string[]) — nullable
    - `type` (enum)
      The type of data provider.
      Values: `default`, `template`
  - `dataViewId` (string) — nullable
    ID of the Timeline's Data View
  - `dateRange` (object) — nullable
    The Timeline's search period.
    - `end` (union string | number) — nullable
    - `start` (union string | number) — nullable
  - `description` (string) — nullable
    The Timeline's description
  - `eqlOptions` (object) — nullable
    EQL query that is used in the correlation tab
    - `eventCategoryField` (string) — nullable
    - `query` (string) — nullable
    - `size` (union string | number) — nullable
    - `tiebreakerField` (string) — nullable
    - `timestampField` (string) — nullable
  - `eventType` (string) — nullable — deprecated
    Event types displayed in the Timeline
  - `excludedRowRendererIds` (enum[]) — nullable
    A list of row renderers that should not be used when in `Event renderers` mode
    Values: `alert`, `alerts`, `auditd`, `auditd_file`, `library`, `netflow`, `plain`, `registry`, `suricata`, `system`, `system_dns`, `system_endgame_process`, `system_file`, `system_fim`, `system_security_event`, `system_socket`, `threat_match`, `zeek`
  - `favorite` (object[]) — nullable
    - `favoriteDate` (number) — nullable
    - `fullName` (string) — nullable
    - `userName` (string) — nullable
  - `filters` (object[]) — nullable
    A list of filters that should be applied to the query
    - `exists` (string) — nullable
    - `match_all` (string) — nullable
    - `meta` (object) — nullable
      - `alias` (string) — nullable
      - `controlledBy` (string) — nullable
      - `disabled` (boolean) — nullable
      - `field` (string) — nullable
      - `formattedValue` (string) — nullable
      - `index` (string) — nullable
      - `key` (string) — nullable
      - `negate` (boolean) — nullable
      - `params` (string) — nullable
      - `type` (string) — nullable
      - `value` (string) — nullable
    - `missing` (string) — nullable
    - `query` (string) — nullable
    - `range` (string) — nullable
    - `script` (string) — nullable
  - `indexNames` (string[]) — nullable
    A list of index names to use in the query (e.g. when the default data view has been modified)
  - `kqlMode` (string) — nullable
    Indicates whether the KQL bar filters the query results or searches for additional results, where:
  * `filter`: filters query results
  * `search`: displays additional search results
  - `kqlQuery` (object)
    KQL bar query.
    - `filterQuery` (object) — nullable
      - `kuery` (object) — nullable
        - `expression` (string) — nullable
        - `kind` (string) — nullable
      - `serializedQuery` (string) — nullable
  - `savedQueryId` (string) — nullable
    The ID of the saved query that might be used in the Query tab
  - `savedSearchId` (string) — nullable
    The ID of the saved search that is used in the ES|QL tab
  - `sort` (union oneOf)
    `object` or `object[]`
    - `columnId` (string) — nullable
    - `columnType` (string) — nullable
    - `sortDirection` (string) — nullable
  - `status` (enum)
    The status of the Timeline.
    Values: `active`, `draft`, `immutable`
  - `templateTimelineId` (string) — nullable
    A unique ID (UUID) for Timeline templates. For Timelines, the value is `null`.
  - `templateTimelineVersion` (number) — nullable
    Timeline template version number. For Timelines, the value is `null`.
  - `timelineType` (enum)
    The type of Timeline.
    Values: `default`, `template`
  - `title` (string) — nullable
    The Timeline's title.
  - `updated` (number) — nullable
    The last time the Timeline was updated, using a 13-digit Epoch timestamp
  - `updatedBy` (string) — nullable
    The user who last updated the Timeline
  - `savedObjectId` (string)
    The `savedObjectId` of the Timeline or Timeline template
  - `version` (string)
    The version of the Timeline or Timeline template
  - `eventIdToNoteIds` (object[]) — nullable
    A list of all the notes that are associated to this Timeline.
    - `created` (number) — nullable
      The time the note was created, using a 13-digit Epoch timestamp.
    - `createdBy` (string) — nullable
      The user who created the note.
    - `updated` (number) — nullable
      The last time the note was updated, using a 13-digit Epoch timestamp
    - `updatedBy` (string) — nullable
      The user who last updated the note
    - `eventId` (string) — nullable
      The `_id` of the associated event for this note.
    - `note` (string) — nullable
      The text of the note
    - `timelineId` (string)
      The `savedObjectId` of the Timeline that this note is associated with
    - `noteId` (string)
      The `savedObjectId` of the note
    - `version` (string)
      The version of the note
  - `noteIds` (string[]) — nullable
    A list of all the ids of notes that are associated to this Timeline.
  - `notes` (object[]) — nullable
    A list of all the notes that are associated to this Timeline.
    - `created` (number) — nullable
      The time the note was created, using a 13-digit Epoch timestamp.
    - `createdBy` (string) — nullable
      The user who created the note.
    - `updated` (number) — nullable
      The last time the note was updated, using a 13-digit Epoch timestamp
    - `updatedBy` (string) — nullable
      The user who last updated the note
    - `eventId` (string) — nullable
      The `_id` of the associated event for this note.
    - `note` (string) — nullable
      The text of the note
    - `timelineId` (string)
      The `savedObjectId` of the Timeline that this note is associated with
    - `noteId` (string)
      The `savedObjectId` of the note
    - `version` (string)
      The version of the note
  - `pinnedEventIds` (string[]) — nullable
    A list of all the ids of pinned events that are associated to this Timeline.
  - `pinnedEventsSaveObject` (object[]) — nullable
    A list of all the pinned events that are associated to this Timeline.
    - `created` (number) — nullable
      The time the pinned event was created, using a 13-digit Epoch timestamp.
    - `createdBy` (string) — nullable
      The user who created the pinned event.
    - `updated` (number) — nullable
      The last time the pinned event was updated, using a 13-digit Epoch timestamp
    - `updatedBy` (string) — nullable
      The user who last updated the pinned event
    - `eventId` (string)
      The `_id` of the associated event for this pinned event.
    - `timelineId` (string)
      The `savedObjectId` of the timeline that this pinned event is associated with
    - `pinnedEventId` (string)
      The `savedObjectId` of this pinned event
    - `version` (string)
      The version of this pinned event
- `totalCount` (number)
  The total amount of results
#### `400`

Bad request. The user supplied invalid data.

`application/json`

- `body` (string)
  The error message
- `statusCode` (number)
## Code examples

#### Console

```console
GET kbn:/api/timelines
```

#### curl

```curl
curl -X GET "${KIBANA_URL}/api/timelines" \
  -H "Authorization: ApiKey ${API_KEY}"
```

## Response examples

#### 200

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "customTemplateTimelineCount": 2,
  "defaultTimelineCount": 90,
  "elasticTemplateTimelineCount": 8,
  "favoriteCount": 5,
  "templateTimelineCount": 10,
  "timeline": [
    {
      "columns": [
        {
          "columnHeaderType": "not-filtered",
          "id": "@timestamp"
        },
        {
          "columnHeaderType": "not-filtered",
          "id": "event.category"
        }
      ],
      "created": 1587468588922,
      "createdBy": "casetester",
      "dataProviders": [
        {
          "enabled": true,
          "excluded": false,
          "id": "id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b",
          "name": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b",
          "queryMatch": {
            "field": "_id,",
            "operator": ":",
            "value": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,"
          }
        }
      ],
      "dataViewId": "security-solution-default",
      "dateRange": {
        "end": 1587456479201,
        "start": 1587370079200
      },
      "description": "Investigating exposure of CVE XYZ",
      "eqlOptions": {
        "eventCategoryField": "event.category",
        "query": "sequence\\n[process where process.name == \u0022sudo\u0022]\\n[any where true]",
        "size": 100,
        "timestampField": "@timestamp"
      },
      "eventType": "all",
      "excludedRowRendererIds": [
        "alert"
      ],
      "favorite": [
        {
          "favoriteDate": 1741337636741,
          "userName": "elastic"
        }
      ],
      "filters": [
        {
          "meta": {
            "alias": "Custom filter name",
            "disabled": false,
            "index": ".alerts-security.alerts-default,logs-*",
            "key": "@timestamp",
            "negate": "false,",
            "type": "exists",
            "value": "exists"
          },
          "query": "{\u0022exists\u0022:{\u0022field\u0022:\u0022@timestamp\u0022}}"
        }
      ],
      "indexNames": [
        ".logs*"
      ],
      "kqlMode": "search",
      "kqlQuery": {
        "filterQuery": "null",
        "kuery": {
          "expression": "_id : *",
          "kind": "kuery"
        },
        "serializedQuery": "{\u0022bool\u0022:{\u0022should\u0022:[{\u0022exists\u0022:{\u0022field\u0022:\u0022_id\u0022}}],\u0022minimum_should_match\u0022:1}}"
      },
      "savedQueryId": "c7b16904-02d7-4f32-b8f2-cc20f9625d6e",
      "savedSearchId": "6ce1b592-84e3-4b4a-9552-f189d4b82075",
      "sort": {
        "columnId": "@timestamp",
        "sortDirection": "desc"
      },
      "status": "active",
      "templateTimelineId": "6ce1b592-84e3-4b4a-9552-f189d4b82075",
      "templateTimelineVersion": 12,
      "timelineType": "default",
      "title": "CVE XYZ investigation",
      "updated": 1741344876825,
      "updatedBy": "casetester",
      "savedObjectId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
      "version": "WzE0LDFd",
      "eventIdToNoteIds": [
        {
          "created": 1587468588922,
          "createdBy": "casetester",
          "updated": 1741344876825,
          "updatedBy": "casetester",
          "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
          "note": "This is an example text",
          "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
          "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
          "version": "WzQ2LDFd"
        }
      ],
      "noteIds": [
        "709f99c6-89b6-4953-9160-35945c8e174e"
      ],
      "notes": [
        {
          "created": 1587468588922,
          "createdBy": "casetester",
          "updated": 1741344876825,
          "updatedBy": "casetester",
          "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
          "note": "This is an example text",
          "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
          "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
          "version": "WzQ2LDFd"
        }
      ],
      "pinnedEventIds": [
        "983f99c6-89b6-4953-9160-35945c8a194f"
      ],
      "pinnedEventsSaveObject": [
        {
          "created": 1587468588922,
          "createdBy": "casetester",
          "updated": 1741344876825,
          "updatedBy": "casetester",
          "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
          "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
          "pinnedEventId": "10r1929b-0af7-42bd-85a8-56e234f98h2f3",
          "version": "WzQ2LDFe"
        }
      ]
    }
  ],
  "totalCount": 100
}
```

#### 400

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "body": "get timeline error",
  "statusCode": 405
}
```