Stream public Events from a Forward Session Thread over Server-Sent Events.
GET /api/v1/forward/sessions/{session_id}/threads/{thread_id}/stream
Request headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <PAT or SAT> |
| Accept | No | text/event-stream is recommended. The connection can still be established when omitted. |
| Last-Event-ID | No | Resume after this Thread Event. |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| session_id | string | Yes | Session ID with the sess_ prefix. |
| thread_id | string | Yes | Thread ID with the sthr_ prefix. |
type, types, types[], include_tool_calls, include_thinking, or event_deltas[]. Passing any of these parameters, even with an empty value, returns 400 invalid_request without opening the downstream stream.
Example request
Stream format
: heartbeat comment lines to keep the connection alive. Consume every frame, filter presentation locally, and persist the latest SSE id for reconnection.
Last-Event-ID
Last-Event-ID must belong to the current Thread:
- A cursor from another Session or Thread returns
404 thread_not_found. - A cursor the runtime identifies as invalid for this Thread returns
400 invalid_event_cursor. - If omitted, replay starts from the first Event in the Thread. No Events are missed, but already consumed Events are delivered again. Use the Event ID for idempotent processing.
- An SSE connection can close because of gateway timeouts, server restarts, or similar conditions. The server does not guarantee that a connection remains open indefinitely. Clients must implement their own reconnection and retry logic. When reconnecting, send the last received Event ID in
Last-Event-IDto resume from that point.
Errors
| HTTP | Type | Code | Condition |
|---|---|---|---|
| 400 | invalid_request | invalid_request | An unsupported selector was provided. |
| 400 | invalid_request_error | invalid_event_cursor | Last-Event-ID is invalid for the current Thread. |
| 401 | authentication_error | authentication_required | The PAT or SAT is invalid or expired. |
| 404 | not_found | session_not_found | The Session does not exist or is not visible to the caller. |
| 404 | not_found_error | thread_not_found | The Thread does not exist, does not belong to the Session, or the cursor points to another Session or Thread. |
| 502 | api_error | runtime_unavailable | The Thread runtime service is unavailable. |
Thread discovery and recovery
The parent Session history or stream exposes child Thread creation and state changes through session.thread_created, session.thread_status_running, session.thread_status_idle, session.thread_status_rescheduled, and session.thread_status_terminated.
After receiving session.thread_created from the parent Session stream, use that Event ID as the first Last-Event-ID for the child Thread stream to avoid missing Events produced between discovery and connection.
If you discover an active child Thread through the Thread list, first read its Event history and then open the stream with the response last_id. After a Thread is archived, you cannot open or resume its stream. Recover lifecycle Events from the parent Session history or stream, and retrieve final state with the get Thread endpoint.