Retrieve an automation run

Fetch one run, with a per-step breakdown of where the contact is in the graph.

GET /v1/automations/{id}/runs/{run_id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The automation id (auto_…).
run_id	string	Yes	The run id (run_…).

Example

curl

curl "https://api.sendgrail.com/v1/automations/$AUTOMATION_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch(
  `https://api.sendgrail.com/v1/automations/${id}/runs/${runId}`,
  { headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` } },
);

const run = await res.json();

Response

{
  "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
    }
  ]
}

For what each field means, see The automation run object.

The steps breakdown is where the run actually is

Retrieve is the read that carries the per-step breakdown — List automation runs leaves it out. Each entry mirrors a step in the automation's graph by key, and carries its own status:

Step status	Meaning
completed	The step ran and the contact moved on.
running	The step is executing right now.
waiting	Paused here — a delay counting down, or a wait_for_event holding for its event or timeout.
failed	The step errored; error says why, and the run's own status is failed.

Only steps the run has reached appear — a step further down a branch the contact never took won't be listed. output carries what the step produced (a send_email reports the email_id it sent), and error is null unless the step failed.

An automation or run from another team answers 404; a sending-access key answers 403. See Errors.