Stream events (SSE notifications)

GET

/v1/sessions/{session_id}/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 ‘agent’ prefix

string

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

Example

agent_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

Event stream. Includes ‘connected’ on open, domain events during streaming, and ‘disconnecting’ before graceful close.

400

Invalid session ID

404

Session not found

500

Internal server error