Runs
How a trigger becomes an execution — dispatch, environments, retries, pauses and the run record.
A run is one execution of a workflow. Every run — editor test, webhook delivery, schedule tick, API call — is durably recorded the moment it is accepted, then executed. If anything in between hiccups, the run is retried by recovery sweeps rather than silently dropped: accepted means it will execute.
Environments
test | production | |
|---|---|---|
| Started by | the editor's Test button, listen-capture, ?environment=test | real trigger deliveries, ?environment=production |
| Executes | the draft | the published snapshot |
| Pinned step data | replayed | ignored — always executes for real |
| Default runs list | hidden | shown |
The run record
Each run records its status (pending → running → completed | failed | cancelled | paused), trigger type and payload, per-step input/output/timing/error, which version actually executed, and its lineage (what it was retried from, which step a partial run started at). Large step payloads offload to the object store transparently; "produced nothing" and "the data cannot be read" are distinct states, never conflated.
Live progress streams to the editor over SSE — and to any client via GET /api/runs/{id}/stream.
Pause and resume
A step can suspend the run — the Delay piece (delay for, delay until), and the Approval piece's wait mode. A paused run frees its worker and survives restarts and deploys:
- Time-based waits are re-enqueued automatically when their moment arrives.
- Webhook waits resume via
POST /api/webhooks/resume/{token}— the posted body lands on{{steps.<wait>.resumeData}}. - Approval links (approve/reject URLs the flow can email out) are the same mechanism, dressed for humans.
A paused run's step outputs are encrypted at rest under the org key.
Failure handling
What a step failure means — retries, timeouts, stop/continue/error-chain routing, and workspace-wide alerting — is configured on the workflow and documented once, in per-step error handling. What the run side adds: Retry from the run page replays what that run actually was — same version snapshot, same starting step, same trigger data.
Cancelling
POST /api/runs/{id}/cancel (or the run page) cancels pending, running and paused runs — an approval nobody will ever answer doesn't have to wait forever.