Stream a task's events
GET /tasks/{id}/stream
Server-sent events for one task. The ChannelEvent union is the whole set: message, reaction, agent_idle, draft_cleared, task_stage and history_complete — the last sent once when the on-connect replay finishes, so a client can tell replayed history from live events without guessing from timestamps.
task_stage is a LAUNCH stage (machine → workspace → tools → agents → ready), not a task status change; nothing here reports status transitions or preview changes.
EventSource cannot set headers, so this route also accepts the org scope as ?org=.
A quiet stream also carries a named ping event every 25s. It is a liveness beat, not a ChannelEvent: a reader that watches it can tell a silent channel from a socket that died half-open, which no amount of listening for message can. Consumers that only listen for message never see it.
Requires: tasks.read
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Resource ULID.
Query Parameters
Section titled “Query Parameters ”Event audience to include.
Event audience to include.
Workspace slug for EventSource clients.
Workspace slug for EventSource clients.
Header Parameters
Section titled “Header Parameters ”Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.
Responses
Section titled “ Responses ”An open SSE stream. Terminates when the client disconnects.
INVALID_REQUEST — a query parameter does not match the route’s query schema, or the same parameter was sent twice. A repeat is rejected rather than resolved: guards read the first value and a parsed object would keep the last.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan