# Streaming a session

Follow a session live with server-sent events, and resume after a disconnect.



`GET /v1/sessions/{session_id}/events` is a [server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)
stream of what happens in a session: its messages, tool calls, questions and state. Opening it
never wakes the machine.

```bash
curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_…/events \
  -H "Authorization: Bearer $HQ_API_KEY"
```

```
id: c1.…
event: session.message.completed
data: {"id":"evt_…","object":"event","type":"session.message.completed","api_version":"2026-11-01","created_at":"…","org_id":"org_…","team_id":"team_…","resource":{"type":"session","id":"sess_…"},"data":{…}}
```

Every event's `data` is an event object: `id` (the same for the same event on every stream, so you
can drop a duplicate; a prompt that returns to a status, for example `typing` again after
`queued`, is a new event with a new `id`), `type`, `api_version`, `created_at`, the organization, team and session it
belongs to, and `data`.

## Events [#events]

| `type`                                              | When                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.message.completed`                         | A user or assistant message, with its text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `session.tool_use.started`, `.completed`, `.failed` | A tool call, with a summary and a `detail_ref`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `session.thinking.completed`                        | A thinking block (its content through the item detail).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `session.notice`                                    | A system notice in the conversation: `kind` and `text`. A message from another Claude session (a teammate or helper session) is a notice with `kind: "peer_message"` and a short `text` such as `Message from another session (release-check): Tests passed`, without the message itself. Routine status messages that arrive together are one notice, such as `3 status updates from another session (release-check)`. A message Claude holds until the person decides is a notice with `kind: "peer_held"`; the session's `session.input_required` (`kind: "peer_hold"`, `answerable_via_api: false`, no message text, and the fixed title `A message from another session is waiting`, never the name the sender gives itself) says it is waiting for a person in HQ. A background job the session started that finished is a notice with `kind: "background_job"` and one line of `text`, such as `Background job finished: Run the tests (exit code 0)`, or `Helper finished: Check the notes` for a helper Claude ran in the background. |
| `session.status`                                    | The session's state changed: `ready`, `busy`, `asleep` and so on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `session.turn.completed`                            | The session finished answering (`busy` became `ready`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `session.input_required`                            | The session is asking something. See [Sessions and prompts](/docs/api/sessions-and-prompts/).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `session.message.status_changed`                    | A prompt you sent moved on (`delivered`, `unconfirmed`, …).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `stream.rotate`                                     | Reconnect now (the server is restarting, or the stream is 50 minutes old).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `stream.reset`                                      | You fell behind or the conversation was reset: read `/items` again, then reconnect. With `reason: "unauthorized"`, the key may no longer follow this session (it was revoked, its person lost access, the team's visibility changed): do not reconnect with it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

A comment line (`: ping`) every 15 seconds keeps the connection open through proxies.

## Resume after a disconnect [#resume-after-a-disconnect]

The last event of each batch carries an SSE `id`. Reconnect with it in `Last-Event-ID` (EventSource
does this for you), or as `?after=`, and you get what you missed, then the live stream:

```bash
curl -N https://api-hq.aiworkforceone.com/v1/sessions/sess_…/events \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Last-Event-ID: c1.…"
```

On `stream.rotate`, reconnect the same way, after the `retry` delay the stream announced (1 second).

## Limits [#limits]

* Up to 4 open streams per session, and a per-plan number per organization
  ([Rate limits](/docs/api/rate-limits/)). One more is refused with `429 too_many_streams`.
* A stream needs `sessions:chat.read` on the session's team, and follows the team's session
  visibility. It is checked again every minute, and at once when access changes in HQ.
