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

# Runs

> A run is one model invocation. Lifecycle, logs, and how to fetch the result.

A **run** is one execution of a model. You create runs with `POST /v1/models/{model_id}/runs`. The `model_id` segment is the model's `provider/slug` and may be more than two segments deep (e.g. `bytedance/seedance/2.0/fast/text-to-video`). Each run has an `id`, a `status_code`, optional logs, and optional node-runs (steps inside a multi-step model).

## Create a run

```bash theme={"dark"}
curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "prompt": "..." },
    "callback_url": "https://your-server.com/webhook"
  }'
```

The response returns immediately with the run's `id` and `status_code: queued`. Save the `id`; that's what every other run endpoint takes.

## Lifecycle

| `status_code`       | Meaning                                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queued`            | Accepted, waiting for compute.                                                                                                                                                                                |
| `dispatching`       | Being submitted to the execution provider.                                                                                                                                                                    |
| `running`           | Executing.                                                                                                                                                                                                    |
| `succeeded`         | Finished, outputs ready.                                                                                                                                                                                      |
| `failed`            | Error during execution. See `failure_message`.                                                                                                                                                                |
| `canceled`          | You canceled it.                                                                                                                                                                                              |
| `partial_succeeded` | Terminal. Multi-output Solutions (and batches) use it when some but not all outputs landed. Treat the same as `succeeded` for polling-loop termination; inspect `outputs[]` to see which entries are present. |

Full enum: [`GET /v1/runs/statuses`](/api-reference/runs/list-run-statuses).

<Note>
  The `status_code` literal is US English (`canceled`, one `l`). The matching callback event name uses UK English (`run.cancelled`, two `l`s), and the batch envelope's `cancelled` count likewise uses two `l`s. Match the upstream surface exactly when filtering on either.
</Note>

## Get the result

Runs are asynchronous by default. Decide per request whether to receive the final payload by callback or by polling.

* **Callback (recommended).** Provide `callback_url` on the create-run request. Runflow POSTs the event envelope there when the run reaches a terminal state. See [Callbacks](/concepts/callbacks).
* **Polling.** Omit `callback_url`. Poll [`GET /v1/runs/{id}`](/api-reference/runs/get-run) until `status_code` is terminal.

Some models also expose a model-specific `sync_mode` input for inline output. Use it only when the individual [model page](/models) documents `sync_mode` and you intentionally want the response body to carry media data. It is per-model, not platform-wide.

## Output shape

On a `succeeded` run, `output` is the normalized payload, not the raw provider response. Code against the normalized shape; do not write fallback chains for provider-specific fields.

```json theme={"dark"}
{
  "outputs": [
    { "type": "image", "url": "https://public.runflow.io/runs/.../0.png", "width": 1024, "height": 1024 }
  ]
}
```

`type` is one of `image | video | audio`. Every entry has a `url` (always present, always non-empty) and may carry additional fields like `width`, `height`, `duration`, `content_type`, `size_bytes` depending on the model.

A handful of legacy provider responses still surface alongside the normalized array during the canonical metadata rollout. Plan for the normalized shape; treat anything else as a forward-compatibility bug to file rather than a fallback path to wire.

On `failed`, `output` is null and the run object carries `failure_code`, `failure_stage`, `failure_message` (see [Errors](/concepts/errors)). On `partial_succeeded`, `output.outputs[]` contains the entries that did land.

## Inspect a run

```bash theme={"dark"}
curl https://api.runflow.io/v1/runs/{id} \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Other reads:

* [`GET /v1/runs/{id}/logs`](/api-reference/runs/search-run-logs) - structured log lines.
* [`GET /v1/runs/{id}/node-runs`](/api-reference/runs/search-flow-node-runs) - per-step records for multi-step models.
* [`GET /v1/runs/{id}/callback`](/api-reference/runs/get-callback-delivery-history) - the event-envelope payload Runflow delivered (or attempted to deliver) to your `callback_url`. Same shape documented under [Callbacks](/concepts/callbacks).

## Related

<CardGroup cols={2}>
  <Card title="Callbacks" icon="webhook" href="/concepts/callbacks">Async result delivery.</Card>
  <Card title="Batches" icon="layer-group" href="/api-reference/batches/list-batches-org-scoped">Run a model on many inputs in one request.</Card>
  <Card title="Errors" icon="triangle-exclamation" href="/concepts/errors">Failed run shape.</Card>
</CardGroup>