> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Stream conversation events > Opens a Server-Sent Events stream of a conversation's live turn activity, emitting named events (agent token, tool, and final event kinds, plus stale when the client has lagged and done when the turn closes) each carrying a JSON data payload and an incrementing id sequence. Resume after a disconnect with the standard Last-Event-ID header or the since_seq query parameter; the optional scope parameter narrows the detail level (and is clamped to the caller's token scope), and view=admin lets an admin attach to a conversation they do not participate in. The caller must have access to the conversation, otherwise 404 is returned. ## Server-Sent Events This endpoint is a long-lived **Server-Sent Events (SSE)** stream, not a one-shot JSON response. Open it with an SSE client and keep it open — it emits one event per agent or platform update until you disconnect. ```http theme={null} GET /v1/api/conversations/{id}/stream Authorization: Bearer hq_pat_... Accept: text/event-stream ``` A comment line (`: ping` / `: idle`) is sent periodically as a keepalive so proxies don't drop the connection — ignore it. ### Event shape Each event has an `event:` name, a monotonic `id:` cursor, and a single-line JSON `data:` payload: ```text theme={null} event: text_delta id: 7Z9aQ2 data: {"text":"Looking up the financials"} ``` ### Common events | `event:` | `data` | Meaning | | -------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------- | | `text_delta` | `{ text }` | A chunk of the assistant's reply — append it. | | `status` | `{ message }` | Progress caption. | | `agent_active` | `{ hint }` | Drive a typing indicator. `hint` is diagnostic — don't render it as user-facing text. | | `tool_call` | `{ id, name, scope, args_summary, args_digest }` | The agent invoked a tool. | | `tool_result` | `{ id, is_error, summary }` | The matching tool call finished. | | `token_usage` | `{ model, input_tokens, output_tokens, cost_usd, … }` | Usage and cost for the turn. | | `final` | `{ text, duration_ms }` | **Terminal for the turn** — the reply is complete. | | `error` | `{ message, recoverable }` | **Terminal for the turn** — it failed. | `final`/`error` end a *turn*, not the stream — the next message produces the next batch. New `event:` names may be added over time; ignore ones you don't recognize (standard SSE behavior). ### Reconnecting `id:` is an opaque, incrementing sequence. On reconnect, send the last one you saw as the `Last-Event-ID` header and the server replays the events you missed from the conversation journal. (`EventSource` sets `Last-Event-ID` automatically on auto-reconnect; on a fresh attach where you can't set the header, pass `?since_seq=` instead.) An optional `?scope=` query parameter narrows which events you receive. To send a message and watch the reply, `POST` to [Post a message](/api-reference/conversations/post-message) (returns immediately) and read the result off this stream. ## OpenAPI ````yaml GET /v1/api/conversations/{id}/stream openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/api/conversations/{id}/stream: get: tags: - conversations summary: Stream conversation events description: >- Opens a Server-Sent Events stream of a conversation's live turn activity, emitting named events (agent token, tool, and final event kinds, plus stale when the client has lagged and done when the turn closes) each carrying a JSON data payload and an incrementing id sequence. Resume after a disconnect with the standard Last-Event-ID header or the since_seq query parameter; the optional scope parameter narrows the detail level (and is clamped to the caller's token scope), and view=admin lets an admin attach to a conversation they do not participate in. The caller must have access to the conversation, otherwise 404 is returned. operationId: stream parameters: - name: id in: path description: Conversation id required: true schema: type: string format: uuid - name: scope in: query description: |- Self-downgrade only. `user` strips diagnostic + accounting fields; `admin` / `integrator` and absent default to the trusted full vocabulary. Unknown values do NOT elevate -- see [`crate::stream_scope::Scope::from_query`]. Auth-derived scope replaces this in #729. required: false schema: type: - string - 'null' - name: since_seq in: query description: |- Explicit "I've already seen up to seq N" cursor for fresh attaches. The standard `EventSource` API doesn't let JS set `Last-Event-ID` on the initial request -- only on automatic reconnects -- so Studio passes its journal high-water mark here to avoid a race where events emitted between the journal fetch and the SSE subscribe vanish into the gap. required: false schema: type: - integer - 'null' format: int64 - name: view in: query description: |- `?view=admin` opts a tenant admin into attaching to a conv stream they don't participate in. Non-admins are silently downgraded. Audited per-attach so admin tail reads of someone else's conv are observable. required: false schema: type: - string - 'null' responses: '200': description: >- Server-Sent Events for the conversation's turn. Each frame is a named event (the agent token/tool/final event kinds, plus `stale` when the client lagged and `done` when the turn closes) carrying a JSON `data` payload and an `id:` sequence. Resume after a drop with the standard `Last-Event-ID` header, or pass `?since_seq=` on a fresh attach. Native EventSource (cookie auth) and fetch-stream (Bearer PAT) both work. content: text/event-stream: {} '404': description: No such conversation for the caller security: - bearer_pat: [] - oauth2: [] components: securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````