Session events

A session publishes a realtime stream of events over Server-Sent Events (SSE) for the life of the call. You receive operator results as they are produced, plus session lifecycle markers and — when enabled — transcript utterances.

Connecting

The events endpoint is authenticated by a short-lived stream token rather than your API key, so it can be opened directly from a browser EventSource:

1. GET /sessions/{session_id}/stream-token — returns a token.
2. Connect to GET /sessions/{session_id}/events?token={token}.

The stream stays open until the call ends or you disconnect. Each SSE message carries the JSON event in its data field and a unique event id in its id field. The Analyse a live call guide walks through a full connect-and-consume example.

Payloads document a stable set of fields but may also carry additional internal or usage fields that are not part of the contract. Read the fields you need and ignore the rest.

Event types

Every event has an event_type discriminator. Switch on it to decide how to read the payload.

operator_result

{
  "event_id": "e2b1…",
  "event_type": "operator_result",
  "session_id": "abc-123",
  "call_id": "call-789",
  "conversation_id": "conv-456",
  "configuration_id": "5f1c…",
  "timestamp_utc": "2026-06-17T10:30:00.000Z",
  "call_elapsed_seconds": 42.0,
  "operator": {
    "name": "fraud-confidence",
    "version": 3,
    "granularity": { "on": "turn", "every": 1, "until_match": null }
  },
  "output_type": "score",
  "result": { "value": 84 },
  "confidence": 0.91,
  "reasoning": "Caller requested an urgent transfer to a new payee…",
  "speaker": "caller",
  "trigger_text": "I need to move the money today.",
  "turn_index": 12
}

• result — the typed result; its shape depends on output_type (see below).
• confidence — the model's self-assessed confidence, 0.0–1.0.
• reasoning — a short natural-language justification, or null.
• operator.granularity — the granularity that produced this result (see Configurations). When the same operator runs at more than one granularity, this is how you tell the deployments apart.
• speaker, trigger_text, turn_index — the turn that triggered the result; null for conversation_end results that run over the whole transcript.

operator_error

Emitted when an operator fails to produce a result. It carries no result, confidence, or reasoning.

{
  "event_id": "9c4d…",
  "event_type": "operator_error",
  "session_id": "abc-123",
  "call_id": "call-789",
  "conversation_id": "conv-456",
  "configuration_id": "5f1c…",
  "timestamp_utc": "2026-06-17T10:30:01.000Z",
  "operator": {
    "name": "fraud-confidence",
    "version": 3,
    "granularity": { "on": "turn", "every": 1, "until_match": null }
  },
  "turn_index": 12
}

transcript_utterance

Emitted only when the session has transcript_events: true. The transcriber emits results incrementally: you receive interim hypotheses as someone is still speaking (is_final: false), each refining the last, then a settled result for the utterance (is_final: true).

{
  "event_type": "transcript_utterance",
  "session_id": "abc-123",
  "call_id": "call-789",
  "speaker": "caller",
  "text": "I need to move the money today.",
  "start": 41.2,
  "utterance_index": 12,
  "is_final": true,
  "confidence": 0.97,
  "duration": 1.8
}

• is_final — false for an interim, still-changing hypothesis; true for the settled text. If you only want stable transcript, ignore interim events and keep those with is_final: true.
• utterance_index — a per-speaker counter. It stays the same across the interim updates of one utterance and only advances after that utterance is finalised, so the interims and the final for the same utterance share an index.
• speaker — caller or recipient.
• start — offset in seconds from the start of the session.
• duration — length of the utterance in seconds.
• confidence — transcription confidence, 0.0–1.0. Lower and less stable on interim results.

session_started

{
  "event_type": "session_started",
  "session_id": "abc-123",
  "call_id": "call-789",
  "conversation_id": "conv-456",
  "started_at": "2026-06-17T10:29:18.000Z"
}

session_ended

{
  "event_type": "session_ended",
  "session_id": "abc-123",
  "call_id": "call-789",
  "conversation_id": "conv-456",
  "configuration_id": "5f1c…",
  "started_at": "2026-06-17T10:29:18.000Z",
  "ended_at": "2026-06-17T10:34:02.000Z",
  "duration_seconds": 284
}

A session normally ends when the call ends; duration_seconds is the analysed duration. After it ends, the durable record is the conversation.

Result shapes

The result field on an operator_result is shaped by the operator's output_type:

See Operators for how output types are defined.