Streaming

GET /v1/runs/{runId}/stream streams a run’s messages live as Server-Sent Events. It’s resumable, and a dropped connection never cancels the run.

curl -N https://api.nicia.ai/v1/runs/$RUN_ID/stream \
  -H "x-api-key: $NICIA_API_KEY"

Events

• message — a run message as it’s produced. The SSE id: of each event is the message’s monotonic sequence.
• status — emitted once when the run reaches a terminal state, carrying the final run with its public status (succeeded / failed / canceled).
• error — emitted if the run can’t be found.

id: 12
event: message
data: {"sequence":12,"role":"assistant","content":"…"}

event: status
data: {"id":"…","state":"closed","status":"succeeded","output":{…}}

Resuming after a disconnect

Each event carries its sequence as the SSE event id. If your connection drops, reconnect with the Last-Event-ID header set to the last sequence you saw — the stream replays everything after that cursor, then continues live. No messages are lost and nothing is duplicated.

curl -N https://api.nicia.ai/v1/runs/$RUN_ID/stream \
  -H "x-api-key: $NICIA_API_KEY" \
  -H "Last-Event-ID: 12"

Browser EventSource clients send Last-Event-ID automatically on reconnect.

WebSocket

The same endpoint upgrades to a WebSocket live stream if you send Upgrade: websocket — used by first-party UIs. For server-to-server integrations the resumable SSE stream above is the simpler, more robust choice.