TimelineClient¶

Client for the Kibana Security Timeline API.

Timelines are the Security Solution’s workspace for investigating events and alerts. The Timeline APIs cover Timeline and Timeline-template CRUD, per-user draft Timelines, favorites, NDJSON export/import, prepackaged-Timeline installation, Timeline copies, investigation notes (/api/note) and pinned events (/api/pinned_event).

Timelines, notes and pinned events are space-scoped saved objects: a Timeline created in one space is not visible from another space. Every method accepts an optional space_id to target a specific space.

class kibana._sync.client.timeline.TimelineClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Security Timeline API.

Timelines are the Security Solution’s workspace for investigating events and alerts. This client covers the full Security Timeline API surface: Timeline and Timeline-template CRUD, per-user draft Timelines, favorites, NDJSON export/import, prepackaged-Timeline installation, Timeline copies, investigation notes (/api/note) and pinned events (/api/pinned_event).

All Timeline resources are space-scoped saved objects: a Timeline created in one space is not visible from another space. Every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a Timeline and attach a note to it
>>> created = client.timeline.create(
...     timeline={"title": "Suspicious logons", "description": "..."}
... )
>>> timeline_id = created.body["savedObjectId"]
>>> client.timeline.create_note(
...     note={"timelineId": timeline_id, "note": "Check host-1 first"}
... )
>>>
>>> # Clean up
>>> client.timeline.delete(saved_object_ids=[timeline_id])

Creating and Managing Timelines

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

# Create a Timeline
created = client.timeline.create(
    timeline={
        "title": "Suspicious logons",
        "description": "Investigating a suspicious logon burst",
        "dateRange": {
            "start": "2026-07-01T00:00:00.000Z",
            "end": "2026-07-02T00:00:00.000Z",
        },
    }
)
timeline_id = created.body["savedObjectId"]

# Get, update, list and delete
fetched = client.timeline.get(id=timeline_id)
client.timeline.update(
    timeline_id=timeline_id,
    version=fetched.body["version"],
    timeline={"title": "Suspicious logons (triaged)"},
)
found = client.timeline.get_all(search="Suspicious", page_size=10)
client.timeline.delete(saved_object_ids=[timeline_id])

Notes and Pinned Events

# Attach an investigation note to the Timeline
note = client.timeline.create_note(
    note={"timelineId": timeline_id, "note": "Check host-1 first"}
)
note_id = note.body["note"]["noteId"]

# Fetch the Timeline's notes, then delete them
notes = client.timeline.get_notes(saved_object_ids=timeline_id)
client.timeline.delete_notes(note_id=note_id)

# Pin an event (by its document _id) and unpin it again
pinned = client.timeline.pin_event(
    event_id="d3a1d35a3e84...", timeline_id=timeline_id
)
client.timeline.unpin_event(
    event_id="d3a1d35a3e84...",
    timeline_id=timeline_id,
    pinned_event_id=pinned.body["pinnedEventId"],
)

Export and Import

# Export Timelines as NDJSON (the parsed body is a list of dicts)
exported = client.timeline.export(
    file_name="timelines.ndjson", ids=[timeline_id]
)

# Import them back (multipart/form-data upload)
result = client.timeline.import_timelines(file=list(exported))
print(result.body["success"], result.body["timelines_installed"])

Drafts, Favorites, Copies and Prepackaged Timelines

# Per-user draft Timeline
draft = client.timeline.get_draft(timeline_type="default")
client.timeline.clean_draft(timeline_type="default")

# Toggle the favorite mark for the current user
client.timeline.favorite(timeline_id=timeline_id, timeline_type="default")

# Copy a Timeline (including notes and pinned events)
copy = client.timeline.copy(
    timeline_id_to_copy=timeline_id, timeline={"title": "Copy"}
)

# Install/update the Elastic prepackaged Timeline templates
client.timeline.install_prepackaged()

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the TimelineClient.

Parameters:

client (Kibana) – The parent Kibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> timeline_client = TimelineClient(kibana_client)

create(*, timeline, status=None, template_timeline_id=None, template_timeline_version=None, timeline_id=None, timeline_type=None, version=None, space_id=None, validate_spaces=None)[source]¶

Create a Timeline or Timeline template.

POST /api/timeline. Creates a new saved Timeline or Timeline template from a SavedTimeline object (title, description, dateRange, columns, dataProviders, filters, …).

Parameters:

timeline (dict[str, Any]) – The SavedTimeline object describing the Timeline (e.g. {"title": ..., "description": ..., "dateRange": {"start": ..., "end": ...}}).
status (str | None) – Timeline status: "active", "draft" or "immutable".
template_timeline_id (str | None) – Unique identifier for the Timeline template (when creating a template).
template_timeline_version (int | None) – Timeline template version number.
timeline_id (str | None) – A unique identifier to assign to the Timeline.
timeline_type (str | None) – Type of Timeline: "default" or "template".
version (str | None) – Version of the Timeline.
space_id (str | None) – Optional space ID to create the Timeline in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created Timeline, including its savedObjectId and version.

Raises:

ApiError – If there was an error creating the Timeline (the spec documents a 405 status for this case).
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

TimelineClient¶

AsyncTimelineClient¶