Streaming Events

Realtime runs

POST /v1/realtime/runs (Agent Runs) and POST /v1/super-agent/realtime/runs (Super Agent) return application/x-ndjson. Use them when your product needs live assistant output, thinking, search and todo cards, opaque tool progress, artifacts, and a terminal event. The event vocabulary is the same. This is a breaking change from the previous text/event-stream framing. Existing EventSource / SSE parsers will not work. There is no dual-frame compatibility shim.

curl -N -X POST https://developer.creao.ai/v1/realtime/runs \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": { "query": "Summarize the latest quarterly report" },
    "model": "anthropic/claude-haiku-4-5"
  }'

Super Agent uses the same stream without agent_id:

curl -N -X POST https://developer.creao.ai/v1/super-agent/realtime/runs \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "query": "Summarize recent Solana TVL changes" },
    "model": "anthropic/claude-haiku-4-5"
  }'

Event format

Each line is one JSON object with a type field:

{"type":"output_text.delta","delta":"The report shows"}

Parse incrementally — do not buffer the body as a single JSON document. Ignore unknown type values. run.created includes render_protocol: 1 so clients can detect this catalog.

Events

Event	Fields	Meaning
`run.created`	`run_id`, `agent_id`, `conversation_id`, `model`, `render_protocol`	The run record and conversation are ready.
`message.created`	`role`, `message_id?`	A new assistant message started.
`output_text.delta`	`delta`	Incremental assistant text.
`thinking.started`	—	The model started a thinking turn.
`thinking.delta`	`delta`	Incremental thinking text. Persist this yourself if you need thinking mid-run; a completed GET may hydrate span content.
`thinking.completed`	—	The thinking turn ended.
`tool.started`	`tool_call_id`, `tool`, `title`	An opaque tool call started. No `input`.
`tool.completed`	`tool_call_id`, `tool`, `status`	An opaque tool call finished (`completed` or `failed`). No `output`.
`search.started`	`search_id`, `kind`, `query`	A web or academic search started.
`search.completed`	`search_id`, `kind`, `query`, `results`	Search finished. Results include `url`, `title`, `domain`, plus academic extras when `kind` is `academic`.
`todo.updated`	`items`	Replace-all todo list. Each item is `{ content, status }`.
`artifact.created`	`artifact_id`, `kind`, `title`, `mime_type?`	A file or image was produced. Mid-stream URLs are omitted; hydrate on GET.
`run.completed`	`run_id`, `status`, `result`, `usage?`	The run completed successfully.
`run.failed`	`run_id`, `status`, `error`, `usage?`	The run reached a terminal failure.
`error`	`code?`	Stream-level error. Message and stack are omitted.
`ping`	`timestamp`	Keepalive about every 15 seconds.

One card wins. When a dedicated search or todo card is emitted for a tool_call_id, the stream does not also emit generic tool.started / tool.completed for that id. Tool input, output, bash commands, file-read paths, and raw object-store URLs never appear on this wire.

Terminal events

Realtime runs end with either run.completed or run.failed. Both include usage.credits when the platform computed a cost greater than zero. usage.models is present only for Super Agent–allowlisted accounts: one aggregated row per (model, kind) — chat plus any vision, image, video, or speech models. Token fields appear only when that capability is token-metered; image-gen and Veo rows use generated_images or duration_seconds instead. Webhooks stay usage-free.

{"type":"run.completed","run_id":"11111111-1111-4111-8111-111111111111","status":"completed","result":{"text":"Done.","blocks":[{"type":"text","content":"Done."}]},"usage":{"credits":1.2,"models":[{"model":"anthropic/claude-haiku-4-5","kind":"chat","input_tokens":800,"output_tokens":40}]}}

{"type":"run.failed","run_id":"11111111-1111-4111-8111-111111111111","status":"failed","error":{"code":"EXECUTION_FAILED"},"usage":{"credits":0.4,"models":[{"model":"anthropic/claude-haiku-4-5","kind":"chat","input_tokens":200,"output_tokens":12}]}}

GET /v1/runs/{run_id} or GET /v1/super-agent/runs/{run_id} matches the terminal usage for that kind. If a failure happens after stream headers have been sent, the API reports it as a terminal stream event instead of a normal JSON error response.

GET snapshot

Completed runs persist a compact result.blocks array alongside result.text. The stream is full fidelity; the snapshot stored on the run row is not. GET /v1/runs/{run_id} and GET /v1/super-agent/runs/{run_id} may add thinking content onto { "type": "thinking" } markers — one block per thinking span, in the same order as the live stream. List and webhook payloads stay marker-only. Artifact url and url_expires_at are added only on GET hydrate. Persist thinking.delta yourself if you need thinking mid-run or after a disconnect before the run completes. Block types: text, thinking (optional content on GET), tool, search, todo, artifact. The same snapshot is written for async POST /v1/runs.

Client notes

Reconnect behavior is your responsibility. If the stream disconnects, fetch the run with GET /v1/runs/{run_id} or GET /v1/super-agent/runs/{run_id} when you have a run ID.
Realtime runs do not support webhook_url; the terminal result is delivered through the stream.
Keep rendering tolerant of new event fields and unknown type values.

Get Started

Agents

Agent Memory

Agent Files

Product Profile

Agent Runs

Super Agent

Account

Workspaces

Workspace Files

Secrets

Skills

Concepts

Realtime runs

Event format

Events

Terminal events

GET snapshot

Client notes

​Realtime runs

​Event format

​Events

​Terminal events

​GET snapshot

​Client notes

Realtime runs

Event format

Events

Terminal events

GET snapshot

Client notes