Skip to main content
View as Markdown

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. 
# 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.

  • Retry & Failure — retry policies, timeouts, dead-letter, idempotency.
  • Triggers — the automation-failure trigger that reacts to failed/exhausted runs.
  • Automations Overview — concurrency and the run lifecycle.