Stream events (SSE notifications)

GET

/v1/sessions/{session_id}/sse

curl --request GET \
  --url https://app.everruns.com/api/v1/sessions/example/sse

• Production API

Establishes a Server-Sent Events (SSE) connection for real-time event streaming.

Connection Lifecycle Events

• connected: Sent immediately when the stream is established. Data: {"status":"connected"}

• disconnecting: Sent before the server closes the connection for graceful cycling. Data: {"reason":"connection_cycle","retry_ms":100} Clients should reconnect immediately using the since_id of the last received event.

Connection Cycling

Connections are automatically cycled every 5 minutes to prevent stale connections through proxies and load balancers. Before closing, the server sends a disconnecting event so clients can reconnect seamlessly without missing events.

Retry Hints

Each SSE event includes a retry: field (in milliseconds) that hints how long clients should wait before reconnecting if the connection is lost:

• During active streaming: 100ms (fast reconnect)
• During idle periods: increases with backoff up to 500ms
• After disconnecting event: 100ms (immediate reconnect)

Resuming Streams

Use the since_id query parameter to resume from a specific event. The server resolves the event ID to its sequence number and returns all subsequent events ordered by sequence, ensuring reliable ordering even under concurrent writes.

Event Type Filtering

Use types for positive filtering (only return these types) and exclude for negative filtering (remove these types). When both are provided, types narrows first, then exclude removes from that set. Both accept only known event types (max 25 per parameter). Unknown types return 400.

Parameters

Path Parameters

session_id

required

string

Session ID (prefixed, e.g., sess_…)

Query Parameters

since_id

One of:

null

null

string

Prefixed identifier with ‘event’ prefix

string

/^event_[0-9a-f]{32}$/

Example

event_01933b5a00007000800000000000001

Filter events with ID greater than this event ID (prefixed format: event_{32-hex})

types

Array<string>

Positive type filter: only return events matching these types (can be specified multiple times). When empty, all types are returned. Example: ?types=turn.started&types=turn.completed

exclude

Array<string>

Event types to exclude from the response (can be specified multiple times). Applied after types filter. Common delta events to exclude: output.message.delta, reason.thinking.delta

Responses

200

Server-Sent Events stream. Each SSE message has the wire shape event: <type>\nid: <event_id>\ndata: <json>\n\n, where <type> is one of the event types in the EventData catalog (turn.started, tool.completed, reason.thinking.delta, …), <event_id> is the event cursor (event_{32-hex} format, usable as since_id on reconnect), and <json> is the body schema below — a serialized Event whose data field carries the event-type-specific payload defined in EventData. Lifecycle framing events (connected, disconnecting) use the same SSE shape but carry a minimal JSON object in data rather than a full Event. See specs/api-streaming.md for the SSE convention.

Media type text/event-stream

Standard event following the Everruns event protocol.

All events have a consistent structure:

• id: Unique event identifier (format: event_{32-hex})
• type: Event type in dot notation (e.g., “input.message”, “reason.started”)
• ts: ISO 8601 timestamp with millisecond precision
• session_id: Session this event belongs to (format: session_{32-hex})
• context: Correlation context for tracing
• data: Event-specific payload (typed via EventData enum)
• metadata: Optional arbitrary metadata
• tags: Optional list of tags for filtering

object

context

required

Correlation context

object

exec_id

Atom execution identifier

string | null

Example

exec_01933b5a00007000800000000000001

input_message_id

User message that triggered this turn

string | null

Example

message_01933b5a00007000800000000000001

parent_span_id

Parent span ID for hierarchical linking (OTel-style). Links this span to its parent in the trace hierarchy.

string | null

span_id

This event’s span ID for observability (OTel-style). Uniquely identifies this span within the trace.

string | null

trace_id

Trace ID for observability (OTel-style). Groups related spans into a single trace. For agent turns, this is typically the turn_id string.

string | null

turn_id

Turn identifier (for turn-scoped events)

string | null

Example

turn_01933b5a00007000800000000000001

data

required

One of:

object

Data for input.message event

object

message

required

The user message

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

object

Text content

object

text

required

string

type

required

string

Allowed values: text

object

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

object

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

object

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

object

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

error_disclosure

Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s error_disclosure capability (capability absent => “standard”), so a client can narrow but never widen disclosure.

string | null

hints

Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge).

Examples: {"setup_connection": true, "rich_media": true}

object | null

locale

Locale override for this message turn (BCP 47, e.g. uk-UA). Overrides the session locale for backend-authored strings and prompts.

string | null

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

external_actor

One of:

null

null

object

External actor identity (for messages from external channels like Slack)

object

actor_id

required

Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”)

string

actor_name

Resolved display name (e.g. “Alice”). Falls back to actor_id if absent.

string | null

metadata

Channel-specific metadata (e.g. team_id, channel_id)

object | null

source

required

Source channel identifier (e.g. “slack”, “discord”)

string

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

phase

One of:

null

null

string

Execution phase for this message.

Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider.

string

Allowed values: Commentary FinalAnswer

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

object

Data for output.message.delta event

Incremental text update during LLM generation. Events are batched (~100ms) to reduce volume while providing real-time feedback.

object

accumulated

required

Accumulated text so far

string

delta

required

The new text chunk

string

turn_id

required

Turn ID this delta belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for output.message.started event

Emitted when the LLM starts generating a response. UI can show a “thinking” indicator until output.message.delta or output.message.completed events arrive.

object

iteration

Current iteration number within this turn (1-based). Useful for UI to show progress during multi-step tool-calling flows.

integer | null format: int32

model

Optional model name being used

string | null

turn_id

required

Turn ID this output belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for output.message.replaced event.

Emitted between the last (suppressed) output.message.delta and the final output.message.completed. Tells the client to discard everything it has accumulated for turn_id and use replacement as the assistant message text. The original model output is never persisted or replayed.

object

guardrail_capability_id

required

Stable ID of the capability that contributed the guardrail (e.g. "prompt_canary_guardrail").

string

guardrail_id

required

Stable ID of the guardrail itself (e.g. "prompt_canary").

string

reason_code

required

Stable machine-readable reason code (e.g. "system_prompt_leak"). Clients localize their copy from this rather than the human text.

string

replacement

required

Replacement text shown to the user and stored as the assistant message.

string

turn_id

required

Turn ID this replacement belongs to.

string

Example

turn_01933b5a00007000800000000000001

object

Data for output.message.completed event

object

error_code

Stable error code for user-facing failures surfaced as assistant text.

string | null

error_disclosure

Error-disclosure mode applied to error_code/error_fields (“generic” | “standard” | “detailed”). Tracking metadata; absent for non-error messages and for paths that predate disclosure modes.

string | null

error_fields

Structured interpolation fields for localized error rendering.

object | null

message

required

The agent message

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

object

Text content

object

text

required

string

type

required

string

Allowed values: text

object

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

object

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

object

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

object

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

error_disclosure

Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s error_disclosure capability (capability absent => “standard”), so a client can narrow but never widen disclosure.

string | null

hints

Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge).

Examples: {"setup_connection": true, "rich_media": true}

object | null

locale

Locale override for this message turn (BCP 47, e.g. uk-UA). Overrides the session locale for backend-authored strings and prompts.

string | null

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

external_actor

One of:

null

null

object

External actor identity (for messages from external channels like Slack)

object

actor_id

required

Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”)

string

actor_name

Resolved display name (e.g. “Alice”). Falls back to actor_id if absent.

string | null

metadata

Channel-specific metadata (e.g. team_id, channel_id)

object | null

source

required

Source channel identifier (e.g. “slack”, “discord”)

string

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

phase

One of:

null

null

string

Execution phase for this message.

Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider.

string

Allowed values: Commentary FinalAnswer

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

metadata

One of:

null

null

object

Metadata about the model used

object

model

required

Model name (e.g., “gpt-4o”, “claude-3-sonnet”)

string

model_id

Model ID (internal identifier)

string | null format: uuid

provider_id

Provider ID (internal identifier)

string | null format: uuid

usage

One of:

null

null

object

Token usage

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for turn.started event

object

input_content

Input message content (for observability)

string | null

input_message_id

required

Input message ID that triggered this turn

string

Example

message_01933b5a00007000800000000000001

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

object

Data for turn.completed event

object

duration_ms

Duration in milliseconds

integer | null format: int64

final_answer_preview

Bounded preview of the final visible assistant answer.

string | null

final_message_id

Canonical assistant message emitted by output.message.completed.

string | null

Example

message_01933b5a00007000800000000000001

input_content

Input message content (for observability, passed through from turn.started)

string | null

iterations

required

Number of iterations in this turn

integer format: int32

llm_call_count

Number of LLM generation calls executed during the turn.

integer | null format: int32

status

Optional explicit completion status for consumers that summarize turns.

string | null

time_to_first_token_ms

First-token latency for the turn, usually from the first LLM generation.

integer | null format: int64

tool_call_count

Number of tool calls completed during the turn.

integer | null format: int32

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Aggregated token usage for all LLM calls in this turn

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for turn.failed event

object

error

required

Error message

string

error_code

Error code

string | null

error_disclosure

Error-disclosure mode applied to error_code/error_fields (“generic” | “standard” | “detailed”). Full diagnostic detail remains available to operators via reason.completed failure events and tracing.

string | null

error_fields

Structured interpolation fields for localized error rendering.

object | null

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.started event

object

agent_id

One of:

null

null

string

Agent ID being used (optional)

string

/^agent_[0-9a-f]{32}$/

Example

agent_01933b5a00007000800000000000001

harness_id

required

Harness ID being used

string

/^harness_[0-9a-f]{32}$/

Example

harness_01933b5a00007000800000000000001

metadata

One of:

null

null

object

Metadata about the model being used

object

model

required

Model name (e.g., “gpt-4o”, “claude-3-sonnet”)

string

model_id

Model ID (internal identifier)

string | null format: uuid

provider_id

Provider ID (internal identifier)

string | null format: uuid

object

Data for reason.completed event

object

duration_ms

Duration of the reason phase in milliseconds

integer | null format: int64

error

Error message if failed

string | null

has_tool_calls

required

Whether tool calls were requested

boolean

success

required

Whether the LLM call succeeded

boolean

text_preview

Text response preview (first 200 chars)

string | null

tool_call_count

required

Number of tool calls requested

integer format: int32

usage

One of:

null

null

object

Token usage from the LLM call

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for the reason.recovered event (EVE-532).

Emitted by ReasonAtom when it detects an in-flight partial assistant message from a previous worker execution and applies the ContinuePartial recovery policy.

object

accumulated_len

required

Character length of the persisted accumulated text.

integer

mode

required

Recovery action taken.

string

Allowed values: finalize restart

turn_id

required

Turn ID the partial belonged to.

string

Example

turn_01933b5a00007000800000000000001

object

Data for capability.usage events.

object

records

required

Array<object>

Single capability usage record. This intentionally carries only stable IDs and small snapshots; prompts, messages, tool arguments, and results are not allowed in reporting facts.

object

capability_id

required

Capability id (prefixed or namespaced) attributing this usage.

string

capability_name

Capability display name for UI. None when the capability is unnamed.

string | null

duration_ms

Total wall-clock duration of the usage in milliseconds (duration-style records). None for count-style records.

integer | null format: int64

tool_name

Concrete tool name when usage_kind is tool_call. None for non-tool usage kinds.

string | null

usage_count

Number of distinct usages recorded in this record (count-style records). None for duration-style records.

integer | null format: int64

usage_kind

required

Discriminator for the kind of usage being recorded (e.g. tool_call, subagent_spawn).

string

Allowed values: configured resolved exposed invoked effect_ran

object

Data for act.started event

object

headline

Human-readable headline for the batch

string | null

tool_calls

required

Tool calls to be executed

Array<object>

Summary of a tool call (compact form without arguments)

object

display_name

Human-readable display name for UI rendering

string | null

id

required

string

name

required

string

narration

Human-readable narration for timeline rendering

string | null

object

Data for act.completed event

object

completed

required

Whether all tool calls completed

boolean

duration_ms

Duration of the act phase in milliseconds

integer | null format: int64

error_count

required

Number of failed tool calls

integer format: int32

headline

Human-readable headline for the completed batch

string | null

success_count

required

Number of successful tool calls

integer format: int32

object

Data for tool.started event

object

display_name

Human-readable display name for UI rendering

string | null

narration

Human-readable narration for timeline rendering

string | null

tool_call

required

The tool call being executed

object

arguments

required

Arguments as JSON

object

id

required

Unique ID for this tool call

string

name

required

Tool name to execute

string

tool_call_fingerprint

Stable fingerprint of tool name + normalized arguments.

string | null

object

Data for tool.completed event

object

capability_id

Capability that contributed the tool definition, when known.

string | null

capability_name

Human-readable capability name snapshot, when known.

string | null

display_name

Human-readable display name for UI rendering

string | null

duration_ms

Duration of the tool call in milliseconds

integer | null format: int64

error

Error message if failed

string | null

narration

Human-readable narration for timeline rendering

string | null

result

Result content (for successful calls)

Array | null

One of:

object

Text content

object

text

required

string

type

required

string

Allowed values: text

object

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

object

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

object

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

object

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

status

required

Status: “success”, “error”, “timeout”, “cancelled”

string

success

required

Whether the tool call succeeded

boolean

tool_call_fingerprint

Stable fingerprint of tool name + normalized arguments.

string | null

tool_call_id

required

Tool call ID

string

tool_name

required

Tool name

string

tool_result_fingerprint

Stable fingerprint of tool name + normalized result/error.

string | null

object

Data for tool.progress event.

Emitted by tools during execution to report interim status updates. This allows long-running tools (e.g., browser operations, sandbox setup) to stream progress feedback between tool.started and tool.completed.

object

display_name

Human-readable display name for UI rendering

string | null

message

required

Human-readable status message (e.g., “Connecting to browser…”)

string

tool_call_id

required

Tool call ID this progress belongs to

string

tool_name

required

Tool name

string

object

Data for tool.output.delta event.

Emitted by tools during execution to stream incremental output chunks. This enables live output rendering (e.g., bash stdout/stderr, command output) between tool.started and tool.completed. Generic — usable by any tool that produces streamed output (bashkit, Daytona exec, subagent speech, etc.).

The consumer accumulates deltas by tool_call_id for display. The final tool.completed result is authoritative — deltas are informational only.

object

delta

required

Incremental output chunk

string

stream

required

Output stream identifier (e.g., “stdout”, “stderr”)

string

tool_call_id

required

Tool call ID this output belongs to

string

tool_name

required

Tool name

string

object

Data for tool.call_requested event

Emitted when the agent needs client-side tool calls executed. The workflow pauses until the client submits results via the API.

object

headline

Human-readable headline for the requested batch

string | null

tool_calls

required

Tool calls that need to be executed by the client

Array<object>

Tool call from LLM response

object

arguments

required

Arguments as JSON

object

id

required

Unique ID for this tool call

string

name

required

Tool name to execute

string

tool_summaries

Optional summaries with display names and narration for UI rendering

Array<object>

Summary of a tool call (compact form without arguments)

object

display_name

Human-readable display name for UI rendering

string | null

id

required

string

name

required

string

narration

Human-readable narration for timeline rendering

string | null

object

Data for transcript.repaired event (EVE-533).

Emitted once per dangling tool call when transcript repair runs before a reason call. A dangling call is an assistant tool_call with no matching ToolResult in the message history. Repair makes the transcript well-formed so the next LLM call succeeds.

object

action

required

Action taken: replay (settled result reused) or synthesize (interrupted placeholder added).

string

Allowed values: replay synthesize

tool_call_id

required

The tool call ID that was repaired.

string

tool_name

The tool name, if known.

string | null

object

Data for the tool.call_repaired event (EVE-600).

Emitted once per malformed tool call handled by the opt-in tool_call_repair capability. outcome is the stable label (local-salvage | re-prompt | gave-up).

object

outcome

required

Stable outcome label: local-salvage, re-prompt, or gave-up.

string

tool_call_id

required

The tool call ID that was inspected/repaired.

string

tool_name

required

The tool name the malformed call targeted.

string

turn_id

required

Turn this repair belongs to.

string

Example

turn_01933b5a00007000800000000000001

object

Data for llm.generation event

Emitted after each LLM API call to provide full visibility into the messages sent to the model and the response received.

object

messages

required

Messages sent to the LLM (including system prompt)

Array<object>

A message in the conversation

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

object

Text content

object

text

required

string

type

required

string

Allowed values: text

object

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

object

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

object

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

object

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

error_disclosure

Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s error_disclosure capability (capability absent => “standard”), so a client can narrow but never widen disclosure.

string | null

hints

Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge).

Examples: {"setup_connection": true, "rich_media": true}

object | null

locale

Locale override for this message turn (BCP 47, e.g. uk-UA). Overrides the session locale for backend-authored strings and prompts.

string | null

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

external_actor

One of:

null

null

object

External actor identity (for messages from external channels like Slack)

object

actor_id

required

Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”)

string

actor_name

Resolved display name (e.g. “Alice”). Falls back to actor_id if absent.

string | null

metadata

Channel-specific metadata (e.g. team_id, channel_id)

object | null

source

required

Source channel identifier (e.g. “slack”, “discord”)

string

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

phase

One of:

null

null

string

Execution phase for this message.

Helps LLMs distinguish between intermediate working commentary and completed answers in multi-step tool-calling flows. Only set on agent (assistant) messages. Providers with native phase support (OpenAI GPT-5.x) send this value in the API request; others derive it from state but don’t send it to the provider.

string

Allowed values: Commentary FinalAnswer

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

metadata

required

Metadata about the generation

object

compaction

One of:

null

null

object

Compaction information if context was compressed before generation Occurs when the conversation context exceeded the model’s limit

object

compacted

required

Whether compaction was performed

boolean

duration_ms

Duration of the compaction operation in milliseconds

integer | null format: int64

input_tokens_after

Number of input tokens after compaction

integer | null format: int32

input_tokens_before

Number of input tokens before compaction

integer | null format: int32

duration_ms

Duration of the generation in milliseconds

integer | null format: int64

Example

1842

error

Error message if generation failed

string | null

Example

provider returned 503

finish_reasons

Finish reasons from the LLM (e.g., [“stop”], [“tool_calls”]) Required for gen-ai semantic conventions

Array<string> | null

Example

[
  "tool_calls"
]

model

required

Model identifier used for generation

string

Example

claude-sonnet-4-5

provider

Provider type (openai, anthropic, etc.)

string | null

Example

anthropic

request_options

One of:

null

null

object

Request-side driver options that were enabled for this generation.

object

metadata

General request metadata passed to the LLM provider for tracking and observability. Includes embedder-supplied labels merged with system tracking keys (session_id, turn_id, etc.).

object

key

additional properties

string

prompt_cache

One of:

null

null

object

Prompt caching configuration for this request.

object

enabled

required

Whether prompt caching was enabled on the request.

boolean

provider_mode

Provider-specific prompt-cache mode used by the driver.

string | null

strategy

required

Strategy used to enable prompt caching.

string

Allowed values: auto

provider_options

Provider-specific request options that do not warrant dedicated fields.

object

key

additional properties

tool_search

One of:

null

null

object

Deferred tool-loading configuration for this request.

object

enabled

required

Whether tool_search was enabled on the request.

boolean

threshold

required

Minimum number of tools before deferred loading activates.

integer

response_id

Unique response identifier from the LLM provider Required for gen-ai semantic conventions

string | null

Example

msg_01ABCDef0123456789

retry

One of:

null

null

object

Retry information if rate limit retries occurred Contains number of retries and total wait time

object

attempts

required

Number of retry attempts made (0 = succeeded on first try)

integer format: int32

total_wait_ms

required

Total time spent waiting between retries in milliseconds

integer format: int64

success

required

Whether the generation was successful

boolean

Example

true

time_to_first_token_ms

Time to first token in milliseconds (streaming latency)

integer | null format: int64

Example

312

usage

One of:

null

null

object

Token usage statistics

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

output

required

Output from the LLM

object

text

Text response from the model

string | null

tool_calls

Tool calls requested by the model

Array<object>

Tool call from LLM response

object

arguments

required

Arguments as JSON

object

id

required

Unique ID for this tool call

string

name

required

Tool name to execute

string

tools

Tools available to the LLM for this generation

Array<object>

Summary of a tool definition (compact form for events)

object

capability_id

Capability that contributed the tool definition, when known.

string | null

capability_name

Human-readable capability name snapshot, when known.

string | null

category

Tool category for namespace grouping.

string | null

description

required

Tool description

string

display_name

Human-readable display name for UI rendering

string | null

name

required

Tool name

string

object

Data for reason.thinking.delta event (extended thinking content from models like Claude)

This event streams incremental thinking/reasoning content from models that support extended thinking mode (e.g., Claude with thinking enabled). The thinking content represents the model’s chain-of-thought reasoning before producing the final response.

object

accumulated

required

Accumulated thinking text so far (convenience for UI)

string

delta

required

The thinking delta (new thinking text since last delta)

string

turn_id

required

Turn ID this delta belongs to (for correlation)

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.item event.

Durable record of an opaque assistant reasoning response item (e.g., OpenAI Responses API reasoning items). Carries provider-supplied opaque artifacts and curated summary text only. Plaintext hidden chain-of-thought is never persisted in this event — emitters must strip any plaintext reasoning content before constructing it.

object

encrypted_content

Provider-encrypted reasoning context, if supplied. Opaque to consumers.

string | null

item_id

required

Provider-assigned identifier for the reasoning item.

string

model

Model identifier reported by the provider, if known.

string | null

provider

required

Provider that produced the reasoning item (e.g., “openai”).

string

summary

Safe summary text segments curated by the provider. Never includes plaintext reasoning content.

Array<string>

token_count

Per-item reasoning token count, when the provider reports one.

integer | null format: int32

turn_id

required

Turn ID this reasoning item belongs to.

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.thinking.started event

Emitted when extended thinking begins during reasoning phase. This signals the model is using chain-of-thought reasoning. UI can show a “thinking” indicator.

object

model

Optional model name being used

string | null

turn_id

required

Turn ID this thinking belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for reason.thinking.completed event

Emitted when extended thinking completes and the model transitions to producing the final response. Contains the complete thinking content.

object

thinking

required

Complete thinking content

string

turn_id

required

Turn ID this thinking belongs to

string

Example

turn_01933b5a00007000800000000000001

object

Data for turn.sealed event (EVE-534).

A sealed turn was deliberately stopped to prevent waste. It is observably distinct from turn.completed (success) and turn.failed (error). The reason is the stable wire form of everruns_core::turn::SealReason ("no_progress" or "budget").

object

detail

Human-readable detail for operators (optional).

string | null

iterations

Iterations completed before the turn was sealed (if known).

integer | null format: int32

reason

required

Why the turn was sealed: "no_progress" (crash-loop with no forward progress) or "budget" (work budget exhausted).

string

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Aggregated token usage before sealing, if available.

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for turn.cancelled event

object

reason

Reason for cancellation

string | null

turn_id

required

Turn identifier

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Token usage before cancellation (if available)

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for session.started event

object

agent_id

Agent ID (optional)

string | null

Example

agent_01933b5a00007000800000000000001

harness_id

required

Harness ID

string

Example

harness_01933b5a00007000800000000000001

model_id

Model ID if specified

string | null

Example

model_01933b5a00007000800000000000001

object

Data for session.activated event (turn started, session now active)

object

input_message_id

required

Input message ID that triggered the turn

string

Example

message_01933b5a00007000800000000000001

turn_id

required

Turn ID that activated the session

string

Example

turn_01933b5a00007000800000000000001

object

Data for session.idled event (turn completed, session now idle)

object

iterations

Number of iterations in the completed turn

integer | null format: int32

turn_id

required

Turn ID that just completed

string

Example

turn_01933b5a00007000800000000000001

usage

One of:

null

null

object

Cumulative token usage for the session at this point

object

actual_cost_usd

Actual cost of this generation in USD, as reported by the provider inline (e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache pricing). None for providers that do not return a cost.

number | null format: double

cache_creation_tokens

Number of tokens written to cache (Anthropic-specific)

integer | null format: int32

cache_read_tokens

Number of tokens read from cache (reduces cost)

integer | null format: int32

effective_cost_usd

Best-effort USD cost for already-aggregated usage. Per-generation usage leaves this unset and derives the effective cost from actual/estimated.

number | null format: double

estimated_cost_usd

Estimated cost of this generation in USD, derived from the model’s static price-table profile. Computed whenever a profile with cost data exists, independently of actual_cost_usd, so estimate-vs-actual drift can be reconciled. None when there is no profile cost data for the model.

number | null format: double

input_tokens

required

Number of input/prompt tokens

integer format: int32

output_tokens

required

Number of output/completion tokens

integer format: int32

object

Data for task lifecycle events (task.created, task.updated).

Carries the full task snapshot so consumers never need a follow-up read; UIs reconcile by task.id (snapshot-then-delta).

object

task

required

A unit of background work owned by a session.

object

artifacts

Array<object>

Typed link to something the task produced.

object

name

required

string

path

Session VFS path, when the artifact lives in the session filesystem.

string | null

type

required

Artifact type: “file”, “url”, “session”, “pr”, etc.

string

url

External URL, when the artifact lives elsewhere.

string | null

attempt

Execution attempt, starting at 1. Incremented on re-attach.

integer format: int32

cancel_requested_at

Cooperative cancel intent. A flag, not a state.

string | null format: date-time

created_at

required

string format: date-time

display_name

required

Human-readable label.

string

error

One of:

null

null

object

Terminal error detail. Timeout/rejection/orphaned are kinds, not states.

object

kind

required

string

message

required

string

finished_at

string | null format: date-time

heartbeat_at

string | null format: date-time

id

required

task_* public ID.

string

input_request

One of:

null

null

object

Pending ask while awaiting_input; cleared when answered.

object

expected

Optional machine-readable description of the expected answer.

object

id

required

Stable ID referenced by the answering message’s in_reply_to.

string

prompt

required

Human/agent-readable prompt.

string

kind

required

Task kind: “subagent”, “external_agent”, “background_tool”, “monitor”, …

string

links

Cross-references owned by a task.

object

child_session_id

Child session, for subagent-shaped tasks. Full transcript lives there.

string | null

remote_task_id

Remote task ID, for tasks wrapping an external protocol task (A2A).

string | null

resource_ids

Session resources (sandboxes, browser sessions) this task holds.

Array<string>

progress

One of:

null

null

object

Structured progress reported by background tools.

object

current

integer | null format: int64

label

string | null

total

integer | null format: int64

unit

string | null

result_path

Machine result in the session VFS: /.tasks/{task_id}/result.json.

string | null

session_id

required

Owning session.

string

spec

Kind-specific input (instructions, tool args, external agent id).

object

started_at

string | null format: date-time

state

required

Lifecycle state of a session task.

Three classes: active (queued, running), interrupted (awaiting_input, resumable), terminal (succeeded, failed, canceled). Timeout and rejection are error.kind values on failed, not states.

string

Allowed values: queued running awaiting_input succeeded failed canceled

state_detail

Short live status line (“polling remote task”, “iteration 4/10”).

string | null

summary

Human-readable outcome.

string | null

updated_at

required

string format: date-time

wake_policy

When outbound task activity wakes the owning session’s agent.

string

Allowed values: silent on_terminal on_activity

worker_id

string | null

object

Data for task lifecycle events (task.created, task.updated).

Carries the full task snapshot so consumers never need a follow-up read; UIs reconcile by task.id (snapshot-then-delta).

object

task

required

A unit of background work owned by a session.

object

artifacts

Array<object>

Typed link to something the task produced.

object

name

required

string

path

Session VFS path, when the artifact lives in the session filesystem.

string | null

type

required

Artifact type: “file”, “url”, “session”, “pr”, etc.

string

url

External URL, when the artifact lives elsewhere.

string | null

attempt

Execution attempt, starting at 1. Incremented on re-attach.

integer format: int32

cancel_requested_at

Cooperative cancel intent. A flag, not a state.

string | null format: date-time

created_at

required

string format: date-time

display_name

required

Human-readable label.

string

error

One of:

null

null

object

Terminal error detail. Timeout/rejection/orphaned are kinds, not states.

object

kind

required

string

message

required

string

finished_at

string | null format: date-time

heartbeat_at

string | null format: date-time

id

required

task_* public ID.

string

input_request

One of:

null

null

object

Pending ask while awaiting_input; cleared when answered.

object

expected

Optional machine-readable description of the expected answer.

object

id

required

Stable ID referenced by the answering message’s in_reply_to.

string

prompt

required

Human/agent-readable prompt.

string

kind

required

Task kind: “subagent”, “external_agent”, “background_tool”, “monitor”, …

string

links

Cross-references owned by a task.

object

child_session_id

Child session, for subagent-shaped tasks. Full transcript lives there.

string | null

remote_task_id

Remote task ID, for tasks wrapping an external protocol task (A2A).

string | null

resource_ids

Session resources (sandboxes, browser sessions) this task holds.

Array<string>

progress

One of:

null

null

object

Structured progress reported by background tools.

object

current

integer | null format: int64

label

string | null

total

integer | null format: int64

unit

string | null

result_path

Machine result in the session VFS: /.tasks/{task_id}/result.json.

string | null

session_id

required

Owning session.

string

spec

Kind-specific input (instructions, tool args, external agent id).

object

started_at

string | null format: date-time

state

required

Lifecycle state of a session task.

Three classes: active (queued, running), interrupted (awaiting_input, resumable), terminal (succeeded, failed, canceled). Timeout and rejection are error.kind values on failed, not states.

string

Allowed values: queued running awaiting_input succeeded failed canceled

state_detail

Short live status line (“polling remote task”, “iteration 4/10”).

string | null

summary

Human-readable outcome.

string | null

updated_at

required

string format: date-time

wake_policy

When outbound task activity wakes the owning session’s agent.

string

Allowed values: silent on_terminal on_activity

worker_id

string | null

object

Data for task message events (task.message.sent, task.message.received).

object

message

required

A message exchanged between a session and one of its tasks.

object

content

required

Array

One of:

object

object

text

required

string

type

required

string

Allowed values: text

object

object

data

required

object

type

required

string

Allowed values: data

created_at

required

string format: date-time

direction

required

Direction of a task message. Inbound = session → task.

string

Allowed values: inbound outbound

id

required

tmsg_* public ID.

string

in_reply_to

Set when this message answers a TaskInputRequest.

string | null

task_id

required

string

task_id

required

string

object

Data for task message events (task.message.sent, task.message.received).

object

message

required

A message exchanged between a session and one of its tasks.

object

content

required

Array

One of:

object

object

text

required

string

type

required

string

Allowed values: text

object

object

data

required

object

type

required

string

Allowed values: data

created_at

required

string format: date-time

direction

required

Direction of a task message. Inbound = session → task.

string

Allowed values: inbound outbound

id

required

tmsg_* public ID.

string

in_reply_to

Set when this message answers a TaskInputRequest.

string | null

task_id

required

string

task_id

required

string

object

Data for context.compacting event (compaction starting).

object

messages_before

required

Number of messages before compaction.

integer

reason

required

Why compaction was triggered.

string

Allowed values: proactive_budget request_too_large manual

strategy

required

Strategy requested (may differ from strategy_used in the completed event).

string

object

Data for context.compacted event (compaction completed).

object

duration_ms

required

Total duration of all compaction steps in milliseconds.

integer format: int64

messages_after

required

Number of messages after compaction.

integer

messages_before

required

Number of messages before compaction.

integer

steps

Individual steps in the cascade.

Array<object>

A single step in a compaction cascade.

object

duration_ms

required

Duration of this step in milliseconds.

integer format: int64

messages_after

required

Number of messages after this step.

integer

strategy

required

Strategy used in this step.

string

strategy_used

required

Combined strategy description (e.g., “observation_masking+native”).

string

object

Data for file.written events emitted when files are written to the session filesystem.

object

created

required

Whether this is a new file (true) or an update to an existing file (false).

boolean

operation

required

Operation type (see FILE_OP_* constants).

string

path

required

File path within the session filesystem (normalized, e.g. “/reports/summary.md”).

string

size_bytes

required

File size in bytes after write.

integer format: int64

object

Data for budget lifecycle events (warning, paused, exhausted, resumed).

object

balance

required

Current remaining balance.

number format: double

budget_id

required

Budget that triggered this event.

string

currency

required

Budget currency (e.g. “usd”, “tokens”).

string

limit

required

Budget limit.

number format: double

message

Human-readable message.

string | null

soft_limit

Soft limit threshold (present for warning/paused events).

number | null format: double

object

Data for budget lifecycle events (warning, paused, exhausted, resumed).

object

balance

required

Current remaining balance.

number format: double

budget_id

required

Budget that triggered this event.

string

currency

required

Budget currency (e.g. “usd”, “tokens”).

string

limit

required

Budget limit.

number format: double

message

Human-readable message.

string | null

soft_limit

Soft limit threshold (present for warning/paused events).

number | null format: double

object

Data for budget lifecycle events (warning, paused, exhausted, resumed).

object

balance

required

Current remaining balance.

number format: double

budget_id

required

Budget that triggered this event.

string

currency

required

Budget currency (e.g. “usd”, “tokens”).

string

limit

required

Budget limit.

number format: double

message

Human-readable message.

string | null

soft_limit

Soft limit threshold (present for warning/paused events).

number | null format: double

object

Data for budget lifecycle events (warning, paused, exhausted, resumed).

object

balance

required

Current remaining balance.

number format: double

budget_id

required

Budget that triggered this event.

string

currency

required

Budget currency (e.g. “usd”, “tokens”).

string

limit

required

Budget limit.

number format: double

message

Human-readable message.

string | null

soft_limit

Soft limit threshold (present for warning/paused events).

number | null format: double

object

Data for voice.session.started.

object

model

required

Provider-side realtime model identifier negotiated for this session.

string

Example

gpt-realtime

reasoning_effort

required

Reasoning effort applied to the realtime model. One of low, medium, high.

string

Example

medium

transport

required

Transport carrying the audio stream. One of webrtc, sip, websocket.

string

Example

webrtc

voice

required

Realtime voice preset selected for this session.

string

Example

alloy

voice_connection_id

required

Prefixed voice connection identifier for the started session.

string

Example

voice_01933b5a00007000800000000000001

object

Data for voice transcript delta/completed events.

object

accumulated

required

Full transcript accumulated for this item up to and including delta.

string

delta

Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion.

string

item_id

Provider-specific identifier of the conversation item being transcribed. None when not yet assigned.

string | null

phase

Transcript phase: user_partial, user_final, assistant_partial, assistant_final. None when not yet classified.

string | null

response_id

Provider-specific identifier of the response stream emitting this transcript. None for user-side transcripts.

string | null

voice_connection_id

required

Prefixed voice connection identifier this transcript belongs to.

string

object

Data for voice transcript delta/completed events.

object

accumulated

required

Full transcript accumulated for this item up to and including delta.

string

delta

Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion.

string

item_id

Provider-specific identifier of the conversation item being transcribed. None when not yet assigned.

string | null

phase

Transcript phase: user_partial, user_final, assistant_partial, assistant_final. None when not yet classified.

string | null

response_id

Provider-specific identifier of the response stream emitting this transcript. None for user-side transcripts.

string | null

voice_connection_id

required

Prefixed voice connection identifier this transcript belongs to.

string

object

Data for voice transcript delta/completed events.

object

accumulated

required

Full transcript accumulated for this item up to and including delta.

string

delta

Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion.

string

item_id

Provider-specific identifier of the conversation item being transcribed. None when not yet assigned.

string | null

phase

Transcript phase: user_partial, user_final, assistant_partial, assistant_final. None when not yet classified.

string | null

response_id

Provider-specific identifier of the response stream emitting this transcript. None for user-side transcripts.

string | null

voice_connection_id

required

Prefixed voice connection identifier this transcript belongs to.

string

object

Data for voice transcript delta/completed events.

object

accumulated

required

Full transcript accumulated for this item up to and including delta.

string

delta

Newly transcribed text chunk delivered in this event. Empty for “final” events that only mark completion.

string

item_id

Provider-specific identifier of the conversation item being transcribed. None when not yet assigned.

string | null

phase

Transcript phase: user_partial, user_final, assistant_partial, assistant_final. None when not yet classified.

string | null

response_id

Provider-specific identifier of the response stream emitting this transcript. None for user-side transcripts.

string | null

voice_connection_id

required

Prefixed voice connection identifier this transcript belongs to.

string

object

Data for voice.session.ended.

object

duration_ms

Total wall-clock duration of the connection in milliseconds. None when the connection never completed an audio handshake.

integer | null format: int64

Example

184500

reason

Free-text end reason captured from the client or server. None when no reason was supplied.

string | null

Example

User hung up after refund confirmed.

voice_connection_id

required

Prefixed voice connection identifier for the ended session.

string

Example

voice_01933b5a00007000800000000000001

object

Data for voice.session.failed.

object

error

required

Error message captured at failure. Provider-formatted; not stable for parsing.

string

Example

realtime provider closed stream: 1011 internal_error

voice_connection_id

required

Prefixed voice connection identifier for the failed session.

string

Example

voice_01933b5a00007000800000000000001

id

required

Unique event identifier (format: event_{32-hex})

string

Example

event_01933b5a00007000800000000000001

metadata

Arbitrary metadata for the event

sequence

Sequence number within session (for ordering)

integer | null format: int32

session_id

required

Session this event belongs to (format: session_{32-hex})

string

Example

session_01933b5a00007000800000000000001

tags

Tags for filtering and categorization

Array<string> | null

ts

required

Event timestamp

string format: date-time

type

required

Event type in dot notation

string

400

Invalid session ID

404

Session not found

500

Internal server error