Skip to main content
One run of a workflow is an execution. It carries an ID, a status, the inputs you passed, and a result once it reaches an Output node. Each execution runs exactly one version of the workflow. The version is fixed when the execution starts. See Versions and publishing.

​
The status set

An execution holds one status at a time. Each status belongs to a phase. No other statuses exist.
An execution starts at queued when the platform holds it back. That covers every row of a batch, and every execution booked for a future time.Everything else starts at starting. That covers a direct API call, and each tick of a recurring schedule that fires one execution.
There is no timeout status. An execution that passes its timeout ends as failed, or as cancelled with the reason timeout.

​
Terminal statuses

completed, failed and cancelled are terminal. Nothing leaves a terminal status.
A terminal execution cannot resume. To retry the work, start a new execution.
Handle all three in your code:
  • completed — read executionResult and continue.
  • failed — log the execution and retry or alert.
  • cancelled — read the cancel reason, then clean up.
A completed run is not always a successful execution. The outcome label inside executionResult tells you what the workflow decided. See Inputs and outputs.

​
Transitions

The platform enforces a state machine. A status change outside this diagram is rejected. Three rules explain the whole diagram:
  1. Terminal is final. completed, failed and cancelled go nowhere.
  2. running is the hub. It reaches every paused status and every terminal status.
  3. A paused run has two exits. Both paused and paused_by_agent resume to running or end as cancelled. Neither becomes failed.
An execution that stays in paused_by_agent past the workflow’s timeout ends as cancelled with the reason timeout.

​
Cancel reasons

A cancelled execution carries a reason. The reason separates a deliberate stop from an exhausted limit. user_requested is the only reason that reflects a deliberate stop. Treat the rest as something to fix — see Debug your workflows.

​
Changing a status yourself

POST /executions/{executionId}/status accepts three values: running, paused and cancelled.
  • Pause suspends the execution. Progress is kept.
  • Resume sends the execution back to running from where it stopped.
  • Cancel stops the run for good.
Cancel beats pause. If a pause request is pending and you cancel, the execution cancels.

​
Watching an execution

Poll GET /executions/{executionId} every 5–10 seconds. Faster polling does not make an execution finish sooner.
Loop until the status is terminal. Do not loop while the status equals running.A loop on running exits the moment the workflow pauses to ask a question. It then reports a half-finished run as final. Handle paused_by_agent and awaiting_confirmation explicitly.
A single-node execution usually finishes in 30–60 seconds. A multi-node execution takes several minutes. For long executions, use a webhook instead of a poll loop. See Webhooks and Slack.

Call a workflow

Start an execution and poll it, with working code

Debug your workflows

Find out why an execution stopped

Versions and publishing

Which version an execution uses

Batch executions

Run one workflow over many rows