The automation run object

A run is one contact's pass through an automation — begun when the trigger fired for them, and carrying a per-step record of how far they got.

Fields

The object returned by GET /v1/automations/{id}/runs/{run_id}, and by list.

Field	Type	Description
object	string	Always "automation_run".
id	string	Run identifier — an opaque, prefixed string, run_…. Stable for the life of the run, and the value you pass as a cursor when paginating.
status	string	The run's overall state — running, completed, failed or cancelled.
started_at	string	ISO 8601 timestamp of when the run began.
completed_at	string | null	ISO 8601 timestamp of when the run finished; null while it is still running.
created_at	string	ISO 8601 timestamp of when the run was created.
steps	array	The per-step breakdown. Only on Retrieve — omitted from list rows.

Run status vs. step status

The run's own status is the whole pass; the steps[] entries each carry their own status, which is a different, narrower set. Keep the two apart:

Run status	Meaning
running	The contact is somewhere in the graph — mid-step or paused on one.
completed	The contact reached the end of the graph.
failed	A step errored and the run stopped.
cancelled	The run was ended before it finished.

The steps breakdown

Present only on Retrieve. Each entry mirrors a step of the automation's graph by key, for the steps this run has actually reached — a step down a branch the contact never took won't appear.

Field	Type	Description
key	string	The step's key, matching the automation's graph.
type	string	The step type — trigger, send_email, delay, and so on.
status	string	This step's state — running, waiting, completed or failed.
started_at	string | null	When this step began.
completed_at	string | null	When this step finished; null while running or waiting.
output	object | null	What the step produced — a send_email reports the email_id it sent. null when there's nothing to report.
error	object | null	Why the step failed; null unless its status is failed.

waiting is the state that makes runs long-lived: a delay counting down, or a wait_for_event holding for its event or timeout. A run can sit running for days with its current step waiting.

{
  "object": "automation_run",
  "id": "run_8Vc1Za4Ht1Nb",
  "status": "running",
  "started_at": "2026-07-16T08:12:04+00:00",
  "completed_at": null,
  "created_at": "2026-07-16T08:12:04+00:00",
  "steps": [
    {
      "key": "welcome",
      "type": "send_email",
      "status": "completed",
      "started_at": "2026-07-16T08:12:04+00:00",
      "completed_at": "2026-07-16T08:12:05+00:00",
      "output": { "email_id": "3f1c9a0e-6c5e-4a2b-9f2d-2b1a7c8e4d31" },
      "error": null
    },
    {
      "key": "wait",
      "type": "delay",
      "status": "waiting",
      "started_at": "2026-07-16T08:12:05+00:00",
      "completed_at": null,
      "output": null,
      "error": null
    }
  ]
}

Ids are opaque

run_… is a prefixed string and nothing more — don't parse it or assume it sorts. The automation it belongs to carries an auto_… id, and an event an evt_…, on the same principle.