Workflow Execution

Once a workflow is enabled, every time it runs it creates an execution — a tracked instance that moves through the workflow’s steps one by one. This guide covers how to start executions, monitor their progress, handle problems, and review past runs.

Starting a workflow

How a workflow starts depends on its trigger type:

Manual — Open the workflow’s detail page and click Run (available while the workflow is enabled). You can optionally provide a JSON trigger payload, which the first step receives as input. You can also start a manual workflow from within a conversation by asking an agent to trigger it.
Event — The workflow starts automatically when a matching event arrives via a webhook or an integration trigger. The event payload is passed to the first step as input data.
Schedule — The workflow starts automatically at the configured cron time. No manual action needed.

Each trigger creates a new, independent execution. If the same workflow is triggered multiple times, multiple executions run in parallel without interfering with each other. Once a workflow has been published, each execution is pinned to the published version it started on — publishing a new version mid-flight never changes a running execution. See Versions & Publishing.

The execution view

The workflow detail page lists the workflow’s executions. Expanding an execution row shows the execution view — each step and its current state.

The execution view displays:

Each step in the workflow, listed in order
The current state of each step (see below)
The agent assigned to each step
Timestamps for when each step started and completed
The output or result of completed steps
The rejection reason or error message, when there is one
Action buttons for the execution: Retry and Cancel, plus Approve and Reject while the execution is paused at a gate

Step states

Each step in an execution moves through the following states:

State	Meaning
Pending	The step has not started yet. It is waiting for a previous step to complete.
Running	The assigned agent is currently working on this step.
Waiting	The step is paused at a gate, waiting for an approver, reviewer, or decision. Distinct from Pending — the work is ready but held by a gate.
Completed	The step finished successfully. The output is available for the next step to use.
Skipped	The step body was not run — for example, a decision gate with `gateTiming: "before"` routed straight past it.
Rejected	An approver explicitly rejected the step at an approval or review gate. The rejection reason is recorded. This is a valid outcome, not an error — rejected executions are fully auditable and can be retried if the approver changes their mind.
Failed	The step encountered an actual error (integration failure, unhandled exception, schema validation failure in strict mode). The execution fails so you can investigate and decide what to do.

Execution statuses

The execution as a whole moves through its own set of statuses:

Pending — The execution has been created but has not started yet
Running — Steps are currently executing
Blocked — The execution is paused at a review, approval, or decision gate
Completed — The execution finished successfully
Rejected — An approver rejected a gate; the execution ended with the rejection reason recorded
Failed — The execution stopped due to an error, or was cancelled

Handling failures

When a step fails, the execution fails at that step. You will see a Failed badge along with an error message explaining what went wrong.

Common reasons for step failures include:

The assigned agent could not complete the task (for example, missing information or an unclear instruction)
An integration the agent tried to use returned an error (for example, an expired OAuth token)
The step’s output did not match its declared output schema in strict mode
A timeout occurred because the step took longer than its time limit (default 15 minutes, maximum 60)

When an execution fails, you have two options in the execution view:

Retry — Retry is smart about the failure mode: it re-dispatches the current step, force-advances past a gate that is stuck waiting, or re-advances from the last completed step — whichever applies. The retry starts the execution from a clean slate with the original trigger payload preserved. Completed executions cannot be retried.
Cancel — Stop the execution entirely.

Rejected executions can be retried the same way — useful when an approver changes their mind or when more context becomes available.

Automatic retries

Some failures never need your attention. When an agent signals that a step failed for a transient reason (for example, a rate-limited integration), the engine automatically re-runs the step — up to three attempts, with short waits between them. Platform-level delivery retries also run behind the scenes, so most transient infrastructure hiccups resolve themselves without operator action. Only failures that persist after these retries surface as a failed execution.

Resolving gates from the execution view

While an execution is blocked at a gate, the execution view shows Approve and Reject buttons alongside the step. Rejecting prompts for a reason, which is recorded on the execution. For decision gates, the approver picks one of the configured options instead, which routes the workflow down the matching transition.

If a gate is stuck — for example, the designated approver is unavailable — clicking Retry on the blocked execution force-advances past the gate. The force-advance is recorded in the audit trail with the acting user, and it is logged as a force-advance, not as an approval by the configured approvers.

Cancelling an execution

To stop an execution that is running or blocked, click Cancel in the execution view. The execution is recorded as failed with a note that it was cancelled, and it is preserved in the execution history. Any steps that were completed before cancellation retain their output. Executions that have already completed or failed cannot be cancelled.

Cancelling an execution does not undo any actions that agents have already performed. For example, if an agent sent an email in Step 2 and you cancel the execution at Step 4, the email is still sent.

Execution history

Executions are retained in the execution history regardless of their outcome, for as long as the workflow exists (deleting a workflow deletes its execution history too). Expand any execution to see its steps, outputs, approval decisions, and error messages.

The execution history is useful for:

Auditing — Reviewing who approved what and when
Debugging — Understanding why a workflow failed
Reporting — Seeing how many times a workflow ran over a given period

Next steps

Creating Workflows — Build a new workflow from scratch.
Steps & Gates — Learn about all step types and gate configurations.
Versions & Publishing — Drafts, test runs, publishing, and rollback.
Integrations — Connect external services so your workflow agents can send emails, update records, and more.