How a run executes and recovers

A run is one execution of a published workflow version. Something fires the trigger, the platform walks the graph one step at a time, and the run ends in a terminal state. Every run is a record of what happened: which version executed, what the trigger sent in, what each step produced, and where it stopped.

Two facts shape everything else on this page. A run is pinned to the exact workflow version it started on, and a finished run is immutable. You never edit a run after the fact. When something goes wrong, you start a new run from a failed one (retry) or you continue a run that is still parked or paused (resume). Understanding which of those two paths applies is the whole job of reading the run model.

What starts a run

A run begins one of two ways.

A live event fires the trigger of the workflow's active version. Only the active version receives live events, so a workflow with no active version produces no runs. The event can be a webhook delivery, a polling cycle, a schedule firing, an inbound email, an RSS fetch, and so on, depending on the trigger you configured. See triggers and actions for how each trigger kind shapes the payload.

A manual start runs the active version on demand, optionally with a payload you supply. This is how you test a published workflow without waiting for a real event. If nothing is published, a manual start returns an error telling you to publish first.

One run is created per activation. For batch-shaped triggers (webhook, RSS, polling) this matters: a poll that returns 50 items fires one run with all 50 items in the trigger payload, not 50 separate runs. To process those items one at a time you add a Loop node downstream. A digest-style workflow that handles the whole batch at once skips the Loop. This is a deliberate design choice so that you decide whether work fans out, rather than the platform guessing.

The seven run statuses

A run reports exactly one status at a time. There are seven.

The three terminal states (completed, failed, cancelled) are final. A run in one of them will never change status on its own. The four non-terminal states can still move: pending becomes running, running can move to waiting, paused, or any terminal state, and a paused run resumes back to running.

pending is usually brief. If a run sits in pending longer than you expect, the most common cause is that the workflow is not actually published and active, so confirm that first.

Why a run waits versus pauses

waiting and paused look similar in a list but mean different things, and they clear differently.

A run is waiting because the workflow itself asked it to. A delay step holds it until a timer fires. An approval step holds it until someone decides. A form step holds it until the form is submitted. A connection request holds it until a client authorizes the app the next step needs. In each case the run resumes automatically once the condition is met. You do not click anything to continue a waiting run that is waiting on a timer; you resolve the underlying thing (approve the task, submit the form, get the client to authorize).

A run is paused because you (or a control action) stopped it. You resume it manually from the run detail page.

There is a third stop that is easy to confuse with a paused run: the workflow itself can be set to Paused (safety) by the safety breaker after a misconfiguration like a runaway loop. That is a workflow status, not a run status, and it stops new runs from starting rather than freezing one in progress. A reached spend cap also stops new runs, but it leaves every workflow's status unchanged and lifts once the cap is raised or removed, or the billing period rolls over. See why a run paused for the full set of reasons and exactly how each one clears.

Reading a failed run

A failed run stopped because one step errored. The recovery decision starts with reading that step.

Open the run, find the first step with status failed in the step timeline (the run detail view links you straight to it and expands it), and read its error. Each failed step carries a structured error you can act on:

• A code, a short machine-readable string such as AUTH_EXPIRED or TIMEOUT.
• An optional class code, the broader kind of failure the code belongs to. Shown as Class: inside the technical detail block, and drawn from a closed engine set, unlike the code itself.
• A message in plain language.
• A provider status, shown as "Provider status: 429" when the failure came from an upstream app's HTTP response.
• A retryable flag, shown as "(retryable)" next to the provider status when re-running the step has a reasonable chance of succeeding.
• An optional technical detail block holding the code, the class code and any extra context for support.

The retryable signal is the fork in the road. A retryable failure (a timeout, a rate limit, a transient 5xx from a provider) usually clears on its own; retrying the run as it is is the right move. A non-retryable failure (a bad credential, a malformed mapping, a missing required field) will fail again identically until you change the workflow, so fix the configuration first, publish, then retry.

There is no fixed catalog of error codes. Codes come from the platform and from the apps your steps call, so treat the shape (code, class code, message, provider status, retryable) as the thing to read, not a closed list to memorize. An On Error route matches on either the code or the class code. Read a failed run walks a full example.

Recovery path one: retry a failed run

A retry starts a brand-new run from a failed one. It does not run the failed run again in place. The original record stays exactly as it was, and the new run gets its own run ID. The two runs link to each other: the new run is marked Retry of the original, and the original is marked Retried as the new one. This is why a retry is safe to reach for: you never destroy the evidence of what went wrong.

Only a failed run can be retried. A completed or cancelled run cannot, and neither can a run that is still in progress. A run that stopped because someone rejected an approval cannot be retried either, because the rejection was a decision and not a failure.

A retry can start in one of two places:

• Retry from failed step starts the new run at the step that failed. The steps that already worked keep their saved results and do not run again, so nothing is saved or sent twice.
• Run again starts the new run at the first step, with the failed run's original trigger data. Every step runs again, including the ones that worked.

You do not pick between them. The run's page offers Retry from failed step whenever the run can pick up where it stopped, and Run again when it cannot.

Two rules decide what a retry reuses:

• A retry runs on your newest published version, not the version the failed run used. This is what lets you fix the failing step, publish, and retry. You can change the failed step and anything after it freely. If you change a step that comes before it, the saved results no longer fit the new version, and only Run again is offered.
• A failure inside a loop or a parallel step restarts the whole block. The new run starts at the loop or the parallel step, so every item or branch runs again, including the ones that worked.

Retry a failed run walks the steps, including how to retry several failed runs at once from the runs list.

Recovery path two: pause, resume, and cancel

The second path is controlling a run that is still alive. Three controls exist, and each is valid only for certain statuses:

• Pause stops a running or pending run. The run moves to paused.
• Resume continues a paused run. It moves back to running. A run waiting for an approval has no Resume button: deciding the approval is what continues it.
• Cancel stops any run that has not already reached a terminal state. Cancelling is permanent: it ends all pending and running steps and the run becomes cancelled. You can record an optional reason; if you do not, it is recorded as "Cancelled by user".

These controls enforce valid transitions on the server, not just in the interface. If your view is stale (say someone else cancelled the run while your page was open) and you fire an action that no longer applies, the action is rejected rather than silently doing the wrong thing. Refresh and look at the current status.

Resuming is not the same as retrying. Resume continues the same run from where it paused. A retry starts a new run. Use resume when a run is merely paused or parked; use retry when a run failed and you want its work done.

Runs are pinned to their version

Each run carries the workflow version it started on, and that pin never changes for the life of the run. This is what makes editing a live workflow safe.

When you edit an active version, the platform forks your changes into a new draft and leaves the running version untouched. Publishing that draft is what swaps which version is live. Runs already in flight keep executing on the version they started on; new events go to the newly published version. Nothing in progress is disrupted, and a run's record always reflects the exact graph that produced it. Workflows explains the draft-to-published lifecycle behind this.

The pin holds for a retry too. A retry does not move the failed run to a newer version. It starts a separate run, and that new run is pinned to the newest published version.

What runs do not do

Be honest with yourself about two things the run model does not give you.

A finished run cannot be "fixed" or edited, and it never runs again in place. Recovery always means a new run (retry), or continuing a run that is still alive (resume). A completed or cancelled run has no retry at all; to do that work again, start a new run.

Run-scoped variables are not available. Steps read each other's output through expressions, but there is no general scratchpad you can write to and read back later in the run. Pass data forward through step output, not through a variable store.

Where to go next

• Retry a failed run walks a retry from the run's page and from the runs list.
• Run and step statuses defines every status with its next action.
• Workflows explains how publishing swaps which version is live without disrupting in-flight runs.