> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session event stream

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

Qoder Cloud Agents streams public Session events over **Server-Sent Events (SSE)**.

## Connection URL

```text theme={null}
GET https://api.qoder.com/api/v1/cloud/sessions/{session_id}/events/stream
```

Request headers:

```text theme={null}
Authorization: Bearer $QODER_PAT
Accept: text/event-stream
```

The stream endpoint supports the `Last-Event-ID` header for reconnection replay. Pass the last event `id` you received; the stream resumes from the event after that ID. Event-type query filters are not currently supported.

Incremental streaming is enabled per Session at creation time:

```json theme={null}
{
  "incremental_streaming_enabled": true
}
```

There is no query parameter or header to enable incremental events for only one stream connection. With the flag enabled, the same stream and list endpoints expose incremental events in addition to the final full events. See [Incremental streaming](/cloud-agents/incremental-streaming) for a quick validation flow.

## SSE format

Each event uses standard SSE fields:

```text theme={null}
id: evt_019e392c0d787cfaa21bda98e06cd913
event: agent.message
data: {"id":"evt_019e392c0d787cfaa21bda98e06cd913","type":"agent.message","content":[{"type":"text","text":"Hello"}],"processed_at":"2026-05-18T03:40:48.888851795Z"}
```

Heartbeat comments may be sent to keep the connection alive.

## Common Event Flow

```text theme={null}
user.message
session.status_running
span.model_request_start
agent.thinking
agent.tool_use
agent.tool_result
agent.message
span.model_request_end
session.status_idle
```

Not every turn contains every event. Managed-agent Sessions can also emit thread events such as `session.thread_created`, `session.thread_status_running`, `agent.thread_message_sent`, and `agent.thread_message_received`.

> Note: Public `agent.thinking` events only carry `id`, `processed_at`, and `type`. 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 omit `processed_at` — treat the field as optional when parsing.

## Incremental events

When `incremental_streaming_enabled` is `true`, clients may receive these top-level incremental event types:

`agent.message_start`, `agent.content_block_start`, `agent.content_block_delta`, `agent.content_block_stop`, `agent.message_delta`, and `agent.message_stop`.

A typical assistant message increment appears in this order:

```text theme={null}
agent.message_start
agent.content_block_start
agent.content_block_delta
agent.content_block_stop
agent.message_delta
agent.message_stop
```

Delta concepts such as text chunks, thinking chunks, and tool input chunks are carried inside `agent.content_block_delta.delta.type`, for example:

```json theme={null}
{
  "type": "agent.content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Hello"
  }
}
```

Current implementations do not stream tool output chunks; tool results still arrive as full `agent.tool_result` events.

## Connection lifecycle

* `session.status_idle` indicates the current turn finished. The connection should stay open and wait for the next turn.
* `session.status_terminated` and `session.deleted` are terminal — the client should stop reconnecting; further events will not arrive.
* `session.status_rescheduled` is a transient signal; the stream may briefly disconnect, then reconnect once the runtime is ready.
* For network drops mid-stream, reconnect with the `Last-Event-ID` header set to the most recently received event ID; the server will replay events after that point.

## 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:

```json theme={null}
{
  "events": [
    {
      "type": "user.tool_confirmation",
      "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
      "result": "allow"
    }
  ]
}
```

When the stream emits `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:

```bash theme={null}
curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events?limit=20&order=desc" \
  -H "Authorization: Bearer $QODER_PAT"
```

List responses use `data` and `next_page`. See [List events](/cloud-agents/api/sessions/list-events) and [Session schemas](/cloud-agents/api/sessions/schemas#public-event-types).