# Automation Runs

Every time a trigger fires, Sovrium records a **run** — a row capturing the trigger payload, each step's status and output, and the final outcome. The runs API lets you list, inspect, replay, and cancel runs for monitoring and debugging.

## Runs API

| Method & Path                           | Purpose                                                   |
| --------------------------------------- | --------------------------------------------------------- |
| `GET /api/automations/runs`             | List runs (paginated, filterable by status / automation). |
| `GET /api/automations/runs/:id`         | Run detail including per-step results.                    |
| `POST /api/automations/runs/:id/replay` | Replay a run, resuming from the first failed step.        |
| `POST /api/automations/runs/:id/cancel` | Cancel a pending or running run.                          |

```bash
# List failed runs of a specific automation
GET /api/automations/runs?status=failed&automationName=welcome-email

# Replay a failed run
POST /api/automations/runs/550e8400-.../replay
```

## Run Statuses

| Status                  | Meaning                                                                     |
| ----------------------- | --------------------------------------------------------------------------- |
| `pending`               | Queued, waiting to execute (or waiting on a concurrency slot).              |
| `running`               | Currently executing.                                                        |
| `completed`             | All actions succeeded.                                                      |
| `completed-with-errors` | Finished, but one or more steps failed under `continueOnError`.             |
| `failed`                | An action errored (triggers the `automation-failure` trigger + retries).    |
| `timed-out`             | Exceeded the automation- or action-level `timeout`. Distinct from `failed`. |
| `exhausted`             | Failed after exhausting all configured retry attempts (dead-letter).        |
| `cancelled`             | Manually cancelled via the API.                                             |

## Step Statuses

| Status      | Meaning                                                                       |
| ----------- | ----------------------------------------------------------------------------- |
| `running`   | Currently executing.                                                          |
| `completed` | Succeeded.                                                                    |
| `failed`    | Errored.                                                                      |
| `skipped`   | Not run — e.g. after a `filter/continue` halt or in partial-failure recovery. |

## Replay & Idempotent Resume

Replaying a partially failed run **skips already-completed steps** and resumes from the first failed step (idempotent resume) — completed steps are never re-executed. Replay always creates a **new** run rather than mutating the original, preserving audit history.

:::callout
**Distinguish duration from error.** A run that exceeds its `timeout` is recorded as `timed-out`, not `failed`, so operators can tell runaway workflows apart from genuine errors. After retries are exhausted, the status becomes `exhausted` and the [`automation-failure` trigger](/en/docs/automation-triggers) fires with the full attempt history.
:::

## Related Pages

- [Retry & Failure](/en/docs/automation-retry-failure) — retry policies, timeouts, dead-letter, idempotency.
- [Triggers](/en/docs/automation-triggers) — the `automation-failure` trigger that reacts to `failed`/`exhausted` runs.
- [Automations Overview](/en/docs/automations-overview) — concurrency and the run lifecycle.