Skip to content

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.

FieldTypeDescription
objectstringAlways "automation_run".
idstringRun identifier — an opaque, prefixed string, run_…. Stable for the life of the run, and the value you pass as a cursor when paginating.
statusstringThe run's overall state — running, completed, failed or cancelled.
started_atstringISO 8601 timestamp of when the run began.
completed_atstring | nullISO 8601 timestamp of when the run finished; null while it is still running.
created_atstringISO 8601 timestamp of when the run was created.
stepsarrayThe 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 statusMeaning
runningThe contact is somewhere in the graph — mid-step or paused on one.
completedThe contact reached the end of the graph.
failedA step errored and the run stopped.
cancelledThe 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.

FieldTypeDescription
keystringThe step's key, matching the automation's graph.
typestringThe step type — trigger, send_email, delay, and so on.
statusstringThis step's state — running, waiting, completed or failed.
started_atstring | nullWhen this step began.
completed_atstring | nullWhen this step finished; null while running or waiting.
outputobject | nullWhat the step produced — a send_email reports the email_id it sent. null when there's nothing to report.
errorobject | nullWhy 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.

json
{
  "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.

Transactional email on your own domain.