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 — Go to the Workflows page, find the workflow, and click Run. If the workflow has input fields, you will be prompted to fill them in first. 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 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.

The execution view

When you click on a workflow and select a specific execution, you see the execution view — a timeline showing each step and its current state.

The timeline 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
Any comments from reviewers or approvers

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.
Rejected	An approver explicitly rejected the step at an approval, review, or decision 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 workflow pauses so you can investigate and decide what to do.

Steps always move forward through these states. A step cannot go back to “Pending” once it has started running.

Monitoring executions

You can monitor all running executions from the Workflows page. Each workflow shows a count of active executions. Click into a workflow to see the list of executions, filtered by status:

Running — Executions currently in progress
Waiting — Executions paused at a review or approval gate
Completed — Executions that finished successfully
Failed — Executions that stopped due to an error
Cancelled — Executions that were manually cancelled

Handling failures

When a step fails, the workflow pauses at that step. You will see a Failed badge on the step 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 the allowed time limit

When a step fails, you have several options:

Retry — Click Retry to have the agent attempt the step again. Retry is smart: it detects the failure mode (running step that died, waiting step whose gate never fired, all-steps-done-but-stuck) and picks the right recovery action. For running or failed steps it re-dispatches the step; for stranded executions it re-emits from the last terminal step; for stuck waiting gates it synthesises an advance. The feedback toast tells you which recovery mode was used.
Edit and retry — Modify the step’s instructions before retrying. This helps if the original instructions were unclear or missing context. Retry also preserves the original trigger payload and wipes stale agent conversation context so the retry starts from a clean slate.
Skip — Mark the step as skipped and continue to the next step. Use this only if the failed step is not critical to the overall process.
Cancel — Stop the entire execution.

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

Automatic stall recovery

Sprigr Teams runs a stall detector in the background. Any execution stuck in running state for more than 5 minutes with no step-level progress is automatically failed with a clear reason code, so stuck workflows do not sit in limbo. Queue-level retries also run behind the scenes with exponential backoff. Most transient infrastructure hiccups resolve themselves within a few minutes without operator action.

Force-advance

Sometimes a step gets stuck — the agent takes too long, or an approval gate is waiting on someone who is unavailable. In these situations, administrators can force-advance the workflow.

To force-advance, click the stuck step in the execution view and select Force Advance. The workflow will skip the current step and move to the next one. If the stuck step was an approval gate, the force-advance counts as an implicit approval from the admin who performed it.

Cancelling an execution

To stop a running execution, open it and click Cancel Execution at the top of the execution view. Cancelled executions are preserved in the execution history with a “Cancelled” status. Any steps that were completed before cancellation retain their output.

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

All executions are retained in the execution history regardless of their outcome. You can filter by status, date range, and trigger type to find specific runs. Click any execution to see its full timeline, step 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.
Integrations — Connect external services so your workflow agents can send emails, update records, and more.