# Flow run statuses

A **flow run** (a flow execution) carries a single status describing where it is in its lifecycle. This page defines the five stored run statuses, the one derived status the API can also return, how they transition, and which are terminal. These are distinct from [work item statuses](./work-item-statuses.md) — do not conflate the two vocabularies.

The status values come from the released API contract and are surfaced in the builder's run history. See [Flow executions](../api/flow-executions) for the API and [Run history](../monitor-review/run-history.md) for the UI.

## The five stored run statuses

| Status | Terminal? | Meaning |
| --- | --- | --- |
| `pending` | No | The run has been accepted but has not started executing yet. |
| `running` | No | The run is actively executing its nodes. |
| `completed` | Yes | The run finished its configured path successfully. |
| `failed` | Yes | The run stopped on an error before completing. |
| `canceled` | Yes | The run was stopped before it completed. |

## The derived `in_review` status

The API's `status` field can also return `in_review`. It is never stored on the run. It is derived at read time and means the run is still open with a work item awaiting human review, so a run reading `in_review` is non-terminal. Filtering by `status=in_review` returns exactly those runs.

Because it is derived rather than stored, `in_review` does not appear in the database constraint that governs the five values above.

## Typical transitions

A run normally moves forward through these states; it does not move backward.

```text
pending ──▶ running ──▶ completed
                   └───▶ failed
                   └───▶ canceled
```

- A run is created in `pending`, then begins executing as `running`.
- From `running` it ends in exactly one terminal state: `completed` on success, `failed` on error, or `canceled` if it was stopped.
- A run that has reached a terminal state does not change status afterward.
- While a run is open and one of its work items is awaiting review, reads report `in_review` in place of `running`.

## Terminal versus non-terminal

- **Non-terminal:** `pending`, `running`, and the derived `in_review`. The run is still in flight; its `completedAt` is not yet set.
- **Terminal:** `completed`, `failed`, `canceled`. The run is finished and its outcome is fixed.

## UI and API naming

The API uses the lowercase values above. The run-history UI shows them as title-cased, colored badges — for example, `completed` displays as **Completed** (green), `failed` as **Failed** (red), and an in-progress run as **Running**.

Run statuses and work item statuses are separate vocabularies — see [Item statuses](./work-item-statuses.md) — and they differ in case. Run statuses are lowercase, work item statuses are uppercase. Both spell cancellation the American way, with one "L".

## No retry or replay is implied by status

A run's status records what happened; it does not imply any automatic retry. There is no mechanism that moves a `failed` run back to `running`. To re-process a case, you start a new run, or — through the API only — use [rerun](../api/flow-executions#rerun-a-flow-execution), which creates a **new** execution (with its own status and `executionId`) from the original inputs and repeats any side effects. Reruns and run comparison are not features of the Monitor & Review UI.

## Where to go next

- [Flow executions](../api/flow-executions) — the API resource, where `status` is returned.
- [Run history](../monitor-review/run-history.md) — browse and inspect runs in the builder.
- [Item statuses](./work-item-statuses.md) — the separate status vocabulary for work items.
- [Concepts glossary](./glossary.md) — concise definitions for every term.