> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creao.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming Events

> Read realtime Developer API runs over Server-Sent Events.

## 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.

```bash theme={null}
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:

```text theme={null}
event: output_text.delta
data: {"delta":"The report shows"}
```

Parse the `event` name first, then parse the JSON `data` payload for that event.

## Events

| Event               | Meaning                                    |
| ------------------- | ------------------------------------------ |
| `run.created`       | The run record and conversation are ready. |
| `message.created`   | A new assistant message started.           |
| `output_text.delta` | Incremental assistant text.                |
| `tool.started`      | A tool call started.                       |
| `tool.completed`    | A tool call completed.                     |
| `artifact.created`  | A file, image, or artifact was produced.   |
| `run.completed`     | The run completed successfully.            |
| `run.failed`        | The run reached a terminal failure.        |
| `error`             | Stream-level error data.                   |
| `ping`              | Keepalive event.                           |

## Terminal events

Realtime runs end with either `run.completed` or `run.failed`.

```text theme={null}
event: run.completed
data: {"run_id":"11111111-1111-4111-8111-111111111111","status":"completed","result":{"text":"Done."}}
```

```text theme={null}
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.