Skip to main content

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.

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.
cancelledYou cancelled it.
partial_succeededBatch-only terminal status. Individual runs do not use it.
Full enum: GET /v1/runs/statuses.

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

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