Skip to main content

​
Realtime runs

POST /v1/realtime/runs returns text/event-stream. Use it when your product needs live assistant output, tool progress, artifacts, and a terminal event. 
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" }
  }'

​
Event format

Each event uses standard Server-Sent Events framing: 
event: output_text.delta
data: {"delta":"The report shows"}
Parse the event name first, then parse the JSON data payload for that event.

​
Events

EventMeaning
run.createdThe run record and conversation are ready.
message.createdA new assistant message started.
output_text.deltaIncremental assistant text.
tool.startedA tool call started.
tool.completedA tool call completed.
artifact.createdA file, image, or artifact was produced.
run.completedThe run completed successfully.
run.failedThe run reached a terminal failure.
errorStream-level error data.
pingKeepalive event.

​
Terminal events

Realtime runs end with either run.completed or run.failed. 
event: run.completed
data: {"run_id":"11111111-1111-4111-8111-111111111111","status":"completed","result":{"text":"Done."}}

event: run.failed
data: {"run_id":"11111111-1111-4111-8111-111111111111","status":"failed","error":{"code":"EXECUTION_FAILED"}}
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.

​
Client notes

  • Reconnect behavior is your responsibility. If the stream disconnects, fetch the run with GET /v1/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. Event payloads may gain additional fields over time.