Skip to main content
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

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_codeMeaning
queuedAccepted, waiting for compute.
dispatchingBeing submitted to the execution provider.
runningExecuting.
succeededFinished, outputs ready.
failedError during execution. See failure_message.
canceledYou canceled it.
partial_succeededTerminal. 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.
The status_code literal is US English (canceled, one l). The matching callback event name uses UK English (run.cancelled, two ls), and the batch envelope’s cancelled count likewise uses two ls. Match the upstream surface exactly when filtering on either.

​
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.
  • Polling. Omit callback_url. Poll GET /v1/runs/{id} 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 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. 
{
  "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). On partial_succeeded, output.outputs[] contains the entries that did land.

​
Inspect a run

curl https://api.runflow.io/v1/runs/{id} \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
Other reads:

Callbacks

Async result delivery.

Batches

Run a model on many inputs in one request.

Errors

Failed run shape.