GET /v1/sessions/{session_id}/sse - Stream events (SSE notifications)
GET /v1/sessions/{session_id}/sse
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 thesince_idof 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
disconnectingevent: 100ms (immediate reconnect)
Resuming Streams
Use the since_id query parameter to resume from a specific event. The server
will only send events with IDs greater than the specified value. Event IDs are
UUID v7 (monotonically increasing), ensuring reliable ordering.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Session ID (prefixed, e.g., sess_…)
Query Parameters
Section titled “Query Parameters ”Event types to exclude from the response (can be specified multiple times). Common delta events to exclude: output.message.delta, reason.thinking.delta
Responses
Section titled “ Responses ”Event stream. Includes ‘connected’ on open, domain events during streaming, and ‘disconnecting’ before graceful close.
Invalid session ID
Session not found
Internal server error