Qoder Cloud Agents streams public Session events over Server-Sent Events (SSE).
Request headers:
By default, an Agent response is written to the Session event history and emitted on the stream as a complete public event, such as
The selection applies only to the current stream connection and does not affect other connections to the same Session. Without
Each event uses standard SSE fields:
Heartbeat comments may be sent to keep the connection alive.
Incremental
Incremental
The SSE
Event delta frames do not contain top-level JSON
Use the SSE
Not every turn contains every event. Managed-agent Sessions can also emit thread events such as
When the stream emits an
When the stream emits
Use the list endpoint for historical events and pagination:
List responses use
Connection URL
agent.message, after generation finishes. This guide calls that complete event a buffered event.
The stream endpoint supports the Last-Event-ID header for reconnection. For ordinary buffered events, the stream resumes after that ID. In-progress event deltas have the additional behavior described below.
Use event_deltas[] to receive an Agent response incrementally on this stream connection. Repeat the parameter to request both supported event types:
event_deltas[], the connection receives only the complete event after the response finishes. Thread event streams do not support this parameter.
SSE Format
Each event uses standard SSE fields:
Event Deltas
Incremental agent.message output begins with event_start, followed by one or more event_delta frames:
agent.thinking output is start-only. No event_delta frames follow:
id:, event_start.event.id, every event_delta.event_id, and the later buffered event id are identical for the same message or thinking event. A typical response with both event types follows this order:
id or processed_at fields. They do not appear in event list/history responses. The buffered agent.message is the authoritative result, and agent.thinking never exposes reasoning content.
Reconnecting During Event Deltas
Use the SSE Last-Event-ID header when reconnecting. Behavior depends on the cursor and whether the message is still being generated:
- The cursor is an event before the current
event_start, and generation is still in progress. The stream replays that message'sevent_startand retained historicalevent_deltaframes, then continues with new deltas. - The cursor equals the current
event_start.event.id, and generation is still in progress. Historical deltas for that message are not replayed. The stream emits only deltas generated after reconnection, followed by the buffered final event. - Generation has completed. Historical deltas for that message are no longer replayed. Reconnecting from an earlier buffered event yields the final
agent.message; reconnecting with that final message's ID resumes after it.
event_start, discard or deduplicate its partial local state, and process the replayed event_start and event_delta frames again.
Common Event Flow
session.thread_created, session.thread_status_running, agent.thread_message_sent, and agent.thread_message_received.
Model request spans
span.model_request_start contains id, processed_at, and type. The matching span.model_request_end contains id, is_error, model_request_start_id, processed_at, and type. Its model_request_start_id equals the corresponding start event's id. When credits are available for the model call, the end event also contains model_usage: {"credits": 1.25}. credits is floored to at most 2 decimal places.
Note: Publicagent.thinkingevents only carryid,processed_at, andtype. The reasoning content is intentionally not exposed; treat the event as a marker that the Agent paused to reason. Several other agent-generated events also omitprocessed_at— treat the field as optional when parsing.
Connection lifecycle
session.status_idleindicates the current turn finished. The connection should stay open and wait for the next turn.session.status_terminatedandsession.deletedare terminal — the client should stop reconnecting; further events will not arrive.session.status_rescheduledis a transient signal; the stream may briefly disconnect, then reconnect once the runtime is ready.- For network drops, reconnect with the
Last-Event-IDheader. See Reconnecting During Event Deltas for the special handling of an in-progress event.
Tool Responses
When the stream emits an agent.tool_use that requires confirmation, send user.tool_confirmation to POST /api/v1/cloud/sessions/{session_id}/events with the tool event ID:
agent.custom_tool_use, execute the custom tool in your client and send user.custom_tool_result.
Event History
Use the list endpoint for historical events and pagination:
data and next_page. See List events and Session schemas.