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

# Stream events

> Stream public Session events over Server-Sent Events.

`GET /api/v1/cloud/sessions/{session_id}/events/stream`

Streams public Session events as Server-Sent Events.

## Path parameters

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

## Query parameters

| Parameter        | Type   | Description                                                                                                                                    |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_deltas[]` | string | Optional, repeatable. Allowed values are `agent.message` and `agent.thinking`. Selects event types to stream incrementally on this connection. |

## Headers

| Header          | Required | Description                                                                                                                                                               |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer $QODER_PAT`                                                                                                                                                       |
| `Accept`        | No       | Use `text/event-stream`                                                                                                                                                   |
| `Last-Event-ID` | No       | Resumes after the specified buffered event ID. When it equals an in-progress event delta ID, historical deltas for that event are skipped and only future output is sent. |

## Example request

```bash theme={null}
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"
```

Request both supported event delta types:

```bash theme={null}
curl -N -G "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream" \
  --data-urlencode "event_deltas[]=agent.message" \
  --data-urlencode "event_deltas[]=agent.thinking"
```

## Response

The response uses `text/event-stream`. Each `data:` payload is one of:

* a complete public [Event object](/cloud-agents/api/sessions/schemas#event-object), called a **buffered event** below, which is recorded in Session event history and includes an SSE `id:` cursor;
* a stream-only [event delta frame](/cloud-agents/api/sessions/schemas#event-delta-stream-frames), whose SSE `id:` is the ID of the event being streamed.

The model request boundaries in buffered output follow the [model request span event schemas](/cloud-agents/api/sessions/schemas#model-request-span-events).

## Stream format

Each event is emitted with standard SSE fields:

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

id: evt_a1b2c3d4e5f6a7b8
event: agent.message
data: {"id":"evt_a1b2c3d4e5f6a7b8","type":"agent.message","content":[{"type":"text","text":"Hello! How can I help you today?"}],"processed_at":"2026-05-18T03:40:50.123456789Z"}

id: evt_b2c3d4e5f6a7b8c9
event: session.status_idle
data: {"id":"evt_b2c3d4e5f6a7b8c9","type":"session.status_idle","stop_reason":{"type":"end_turn"},"processed_at":"2026-05-18T03:40:50.987654321Z"}
```

The server sends `: heartbeat` comment lines periodically to keep the connection alive.

### Event delta frames

Incremental `agent.message` output emits `event_start` followed by one or more `event_delta` frames. Incremental `agent.thinking` output emits only `event_start`.

```text theme={null}
id: evt_00jjujk9fbnr55q5rtyp
event: event_start
data: {"event":{"id":"evt_00jjujk9fbnr55q5rtyp","type":"agent.thinking"},"type":"event_start"}

id: evt_00jjujk9fbnr4wkj2gh8
event: event_start
data: {"event":{"id":"evt_00jjujk9fbnr4wkj2gh8","type":"agent.message"},"type":"event_start"}

id: evt_00jjujk9fbnr4wkj2gh8
event: event_delta
data: {"delta":{"content":{"text":"Hello","type":"text"},"index":0,"type":"content_delta"},"event_id":"evt_00jjujk9fbnr4wkj2gh8","type":"event_delta"}
```

Each frame's SSE `id:` is the ID of the event being streamed. Its JSON payload does not include top-level `id` or `processed_at` fields. Event delta frames do not appear in list/history responses. Retained deltas are available for reconnect only while the event is still in progress; after the buffered `agent.message` is written, historical deltas are no longer replayed.

## Reconnection

For normal buffered events, `Last-Event-ID` resumes after the specified event. An in-progress incrementally streamed event has additional behavior because its `event_start`, all `event_delta` frames, and final buffered event share one ID:

1. A cursor before the current `event_start` replays its retained start and historical deltas while generation is still in progress.
2. A cursor equal to the in-progress event ID skips its historical deltas and receives only future deltas and the final buffered event.
3. After generation completes, reconnecting from an earlier buffered event returns the final `agent.message`, not historical deltas.

To rebuild an entire in-progress event, reconnect from the buffered event immediately before its `event_start` and reprocess frames keyed by their shared event ID. See [SSE Event Stream](/cloud-agents/api/sessions/events-stream#reconnecting-during-event-deltas) for the complete client guidance.

## Errors

| HTTP | Type                    | Trigger                                                                                                       |
| ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | `Last-Event-ID` identifies an archived or non-public event, or `event_deltas[]` contains an unsupported value |
| 401  | `authentication_error`  | PAT invalid or expired                                                                                        |
| 404  | `not_found_error`       | Session or the event referenced by `Last-Event-ID` does not exist                                             |

### Example: 404 Session not found

```json theme={null}
{
  "error": {
    "message": "Session 'sess_doesnotexist_xxxxxxxxxxxxxxxxxxxxxxxx' was not found.",
    "type": "not_found_error"
  },
  "request_id": "b5822072-f264-48da-9d61-6d48ffb07551",
  "type": "error"
}
```

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.