API Reference
API Reference

Get Session Timeline By Id

Consolidated, time-ordered timeline of a session's events.

GET/api/v1/sessions/timeline/{session_id}

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

Path parameters

session_id string path required

Responses

200Successful Response

application/json

response SessionTimelineResponse required
3 fields
session_idstringrequired

Internal ID of the session

session_startstring (date-time) | nulloptional

The call's start (placement) time; the zero point for all offsets. Falls back to the first transcript turn for legacy sessions with no session_start event.

eventsTimelineEvent[]required

All events, ordered by timestamp ascending

Item schema
itemsTimelineEventrequired

A single normalized event on the consolidated session timeline.

14 fields
kindenum<string>required

Which stream this event came from

Allowed values ["transcript","tool","latency"]
timestampstring (date-time)required

Absolute time of the event (for ordering)

offsetstringrequired

Time since session start, formatted MM:SS (or HH:MM:SS)

turn_indexinteger | nulloptional

0-based index of the transcript turn. Transcript events carry their own turn index; tool/latency events carry the index of the nearest preceding turn they bind to. None only for non-transcript events that precede the first transcript turn.

sourcestring | nulloptional

"user" or "agent" (transcript events)

textstring | nulloptional

Message content (transcript events)

langstring | nulloptional

Language code (transcript events)

categorystring | nulloptional

tool | llm | tts | stt | http. A tool call surfaces once, as a kind=tool event; its redundant tool-latency measurement is dropped from the timeline.

labelstring | nulloptional

Tool name (tool events) or the latency measurement name (e.g. stt_processing)

metadatastring[] | nulloptional

Provider/model parts of a latency label

Item schema
itemsstringrequired
duration_msnumber | nulloptional

Duration of the event in milliseconds

tool_requeststring | nulloptional

Tool request payload, JSON-encoded

tool_resultstring | nulloptional

Tool response payload, JSON-encoded

tool_errorstring | nulloptional

Tool error payload, JSON-encoded

Response example
{
  "session_id": "string",
  "session_start": "string",
  "events": [
    {
      "kind": "string",
      "timestamp": "string",
      "offset": "string",
      "turn_index": "string",
      "source": "string",
      "text": "string",
      "lang": "string",
      "category": "string",
      "label": "string",
      "metadata": "string",
      "duration_ms": "string",
      "tool_request": "string",
      "tool_result": "string",
      "tool_error": "string"
    }
  ]
}
422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}