Stream events (SSE)

GET /v1/sessions/{session_id}/events/stream Receives all events in a session in real time through Server-Sent Events (SSE). After the connection is established, the server pushes the session’s complete event history and continues to stream new events as they occur.

Path parameters

Parameter	Type	Description
`session_id`	string	Session ID with the `sess_` prefix

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer $QODER_PAT`
`Accept`	Recommended	`text/event-stream`
`Last-Event-ID`	No	Resume after this event ID. The ID must belong to the session.

Query parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by event type. Supports comma-separated values and repeated parameters.
`types[]`	string	No	Array-style alternative to `type`. Pass multiple `types[]=...` parameters to stream several event types.

Example request

curl -N -X GET "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"

Example response

HTTP 200 OK Content-Type: text/event-stream Each event follows the standard SSE format:

id: <event_id>
event: <event_type>
data: <json_payload>

SSE format examples

Note: The JSON in each SSE data line is a completely flat structure — all fields (such as name, input, evaluated_permission, content, is_error, etc.) sit at the top-level object with no additional nesting wrapper. The content field is always in array format in SSE output: [{"type": "text", "text": "..."}].

User message:

id: evt_019e392c0d787cfaa21bda98e06cd913
event: user.message
data: {"id": "evt_019e392c0d787cfaa21bda98e06cd913", "type": "user.message", "content": "Hello", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "created_at": "2026-05-18T03:40:48.888851795Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:40:48.888851795Z", "schema_version": "1.0"}

Session scheduled:

id: evt_771c1195bcbd4a07834d4ed4dd6450ca
event: session.status_running
data: {"id": "evt_771c1195bcbd4a07834d4ed4dd6450ca", "type": "session.status_running", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "created_at": "2026-05-18T03:40:50.321Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:40:50.321Z", "schema_version": "1.0"}

Agent reply:

id: evt_f8599c68e7784f2d8c490af1b3056716
event: agent.message
data: {"id": "evt_f8599c68e7784f2d8c490af1b3056716", "type": "agent.message", "content": [{"text": "Got it! Message received.", "type": "text"}], "turn_id": "turn_019e392d6aad7158b377c039c6ba5db3", "created_at": "2026-05-18T03:42:41.194Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "processed_at": "2026-05-18T03:42:41.194Z", "schema_version": "1.0"}

Agent tool call:

id: evt_01JZ6Q3FB6SG8F7J1M2N
event: agent.tool_use
data: {"id": "evt_01JZ6Q3FB6SG8F7J1M2N", "type": "agent.tool_use", "schema_version": "1.0", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "name": "Bash", "input": {"command": "echo hello"}, "evaluated_permission": "allow", "processed_at": "2026-05-18T03:41:05.000Z"}

Custom tool request:

id: evt_01JZ6R1V9Z8K2M3N4P5Q
event: agent.custom_tool_use
data: {"id": "evt_01JZ6R1V9Z8K2M3N4P5Q", "type": "agent.custom_tool_use", "schema_version": "1.0", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "name": "lookup_order", "input": {"order_id": "ord_123"}, "processed_at": "2026-05-18T03:41:05.000Z"}

Tool result:

id: evt_01JZ6Q5Y0S1H2G3F4E5D
event: agent.tool_result
data: {"id": "evt_01JZ6Q5Y0S1H2G3F4E5D", "type": "agent.tool_result", "schema_version": "1.0", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "tool_use_id": "toolu_bdrk_01T42NPLcKrBvLJfWgGt3QMt", "name": "Bash", "content": [{"type": "text", "text": "hello\n"}], "is_error": false, "processed_at": "2026-05-18T03:41:06.000Z"}

Session idle (turn complete):

id: evt_a289470296c94e7ba8d7ea562efe5925
event: session.status_idle
data: {"id": "evt_a289470296c94e7ba8d7ea562efe5925", "type": "session.status_idle", "usage": {"input_tokens": 150, "output_tokens": 42, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}, "status": "idle", "turn_id": "turn_019e392d6aad7158b377c039c6ba5db3", "created_at": "2026-05-18T03:42:41.195Z", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "stop_reason": {"type": "end_turn"}, "processed_at": "2026-05-18T03:42:41.195Z", "schema_version": "1.0"}

Session idle (requires action):

id: evt_01JZ6R2E7H9M0N1P2Q3R
event: session.status_idle
data: {"id": "evt_01JZ6R2E7H9M0N1P2Q3R", "type": "session.status_idle", "status": "idle", "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec", "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def", "stop_reason": {"type": "requires_action", "event_ids": ["evt_01JZ6R1V9Z8K2M3N4P5Q"]}, "schema_version": "1.0"}

Event types

Full event type list:

`event` (SSE field)	Description
`user.message`	User-sent message
`session.status_running`	Agent started processing
`agent.thinking`	Agent thinking (internal reasoning)
`agent.message`	Agent-generated reply
`agent.tool_use`	Agent invoked a built-in tool
`agent.tool_result`	Tool execution result
`agent.custom_tool_use`	Agent requested a client-side custom tool
`user.tool_confirmation`	User approved or denied a pending tool call
`user.custom_tool_result`	User/client returned a custom tool result
`agent.mcp_tool_use`	Agent invoked an MCP tool
`agent.mcp_tool_result`	MCP tool execution result
`agent.artifact_delivered`	Agent delivered a file through `DeliverArtifacts`
`session.status_idle`	Processing complete, session back to idle
`session.error`	Error occurred during processing
`session.thread_created`	A new child thread was created (Managed Agents)
`session.thread_status_running`	Child thread started running (Managed Agents)
`session.thread_status_idle`	Child thread returned to idle (Managed Agents)
`session.thread_status_terminated`	Child thread was archived or terminated (Managed Agents)
`agent.thread_message_sent`	Inter-thread message sent (Managed Agents)
`agent.thread_message_received`	Inter-thread message received (Managed Agents)

The stream filters out internal event types such as agent.raw, agent.system, turn_completed, turn_cancelled, turn_failed, terminated, span.model_request_start, span.model_request_end, and pending_action.*.

Typical event lifecycle

A complete conversation turn typically streams events in this order:

user.message – User message enqueued
session.status_running – Agent started
agent.thinking – Agent internal reasoning
agent.message – Agent generates reply
session.status_idle – Turn complete, or paused with requires_action

Client implementation guidance

Use the EventSource API or an HTTP client that supports SSE
Use the standard Last-Event-ID header to resume after a known event ID
Listen for session.status_idle; stop_reason.type tells whether the turn completed or paused for action
When session.status_idle.stop_reason.type is requires_action, respond to the listed event_ids with user.tool_confirmation or user.custom_tool_result
Use the turn_id field to correlate all events belonging to the same turn
The connection stays open until the client disconnects; the server continues to push new events

Errors

HTTP	Type	Trigger
401	`authentication_error`	PAT invalid or expired
404	`not_found_error`	Session does not exist

See Errors for the full error envelope.

Session event stream

Stream agent thinking, messages, tool calls, and status over SSE.

​Path parameters

​Headers

​Query parameters

​Example request

​Example response

​SSE format examples

​Event types

​Typical event lifecycle

​Client implementation guidance

​Errors

​Related