AI Workforce OneHQDocs

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

typeWhen
session.message.completedA user or assistant message, with its text.
session.tool_use.started, .completed, .failedA tool call, with a summary and a detail_ref.
session.thinking.completedA thinking block (its content through the item detail).
session.noticeA 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.statusThe session's state changed: ready, busy, asleep and so on.
session.turn.completedThe session finished answering (busy became ready).
session.input_requiredThe session is asking something. See Sessions and prompts.
session.message.status_changedA prompt you sent moved on (delivered, unconfirmed, …).
stream.rotateReconnect now (the server is restarting, or the stream is 50 minutes old).
stream.resetYou 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.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.