Concepts
A run is one execution of a workflow definition. It tracks the input values, a snapshot of the workflow spec, and the current execution state from the moment it enters the queue through to a terminal outcome. Workers claim individual jobs spawned by a run's steps — not the run itself. The action log records what each step did.
The model
Each run carries:
- A status — one of
queued,running,suspended,completed, orfailed. - A spec snapshot — the workflow spec captured at run creation. Edits to the definition after that point do not affect in-flight runs.
- Inputs — the key-value map supplied at start time.
- An attempt counter — 1-based, increments on each retry.
- A parent run ID — set when this run was spawned by a fan-out step inside another run.
- An external ID — a caller-supplied idempotency or correlation key, filterable in the list API.
- A
cancel_requestedflag — set by a cancel call; workers observe it on their next heartbeat and stop cooperatively.
The server owns run progression. Workers claim jobs — the claimable units created by worker-action steps — not the run itself.
Starting a run
curl -X POST "$MOBIUS_API_BASE/v1/projects/acme/runs" \
-H "Authorization: Bearer $MOBIUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"definition_id": "wf_01abc",
"inputs": { "doc_id": "doc_999" },
"external_id": "order-42"
}'The endpoint returns 202 Accepted with the run record at queued status. The engine schedules the first step; workers polling the queue pick up the resulting job. Pass spec instead of definition_id to start an ephemeral run — no workflow definition is created, and the run carries an empty definition_id.
Lifecycle
| State | Entered when | Left when |
|---|---|---|
queued | Run is created or resumed | Worker claims it → running; or max attempts exhausted → failed |
running | A worker claims the run | All steps complete → completed; unrecoverable error → failed; step awaits external input → suspended |
suspended | A step waits on a signal, interaction, or sleep | Signal arrives or interaction is responded to → queued |
completed | All steps succeed | Terminal |
failed | Run exceeds retries or hits a fatal error | Terminal; re-enqueue via POST /v1/projects/{project}/runs/retries |
Where you see it
- Dashboard — Projects → <project> → Runs lists all runs, filterable by status (All, Running, Queued, Suspended, Failed, Completed). Active runs appear under Active now; terminal runs appear under Recent.
- API — the Runs tag group covers starting, listing, inspecting, cancelling, retrying, and streaming run events.
- Events — subscribe to
GET /v1/projects/{project}/runs/{id}/events(SSE) for a per-run stream ofrun_updated,job_updated, andaction_appendedframes; useGET /v1/projects/{project}/runs/eventsfor the project-wide stream.