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
stream of what happens in a session: its messages, tool calls, questions and state. Opening it
never wakes the machine.
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
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. |
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
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:
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
- Up to 4 open streams per session, and a per-plan number per organization
(Rate limits). One more is refused with
429 too_many_streams. - A stream needs
sessions:chat.readon 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.