---
title: "List automation runs"
method: GET
path: "/v1/sites/{site_id}/automations/{automation_id}/runs"
tags: ["Automations"]
---

# List automation runs

`GET /v1/sites/{site_id}/automations/{automation_id}/runs`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/automations/{automation_id}/runs`
- Auth: HTTP bearer

Runs of the automation by id, oldest first; `order=newest` gives the latest
first. A run is one pass of a contact through the automation, with its
status, its error and the steps it went through. Call it to find out what
happened to a contact in the automation (`contact_id`), why runs failed
(`status=failed`), who started a run (`caller`) and with what values
(`data`). Counts by status are in `get_automation_stats`.

Events waiting to be picked up are not runs yet and are not listed, so
`queued` here can be lower than in the statistics. Runs of contacts deleted
since are not listed, and a step removed from the automation since is left
out of `steps`. `run_start:<id>` in `list_contact_activity` is the run `id`, and
its `source_id` is the automation.

## Path parameters

- `site_id` integer, required
- `automation_id` integer, required: Automation id from `list_automations`

## Query parameters

- `contact_id` integer: Only runs of this contact, id from `list_contacts`
- `status` 'queued' | 'ongoing' | 'done' | 'ineligible' | 'failed': queued: waits to start. ongoing: running, waiting in a delay step or on hold. done: finished. ineligible: finished by being skipped. failed: finished with an error.
- `started_since` string, date-time: Only runs started at or after this moment; without an offset, taken as UTC; a plain date means its start
- `cursor` string: `next_cursor` of the previous page, sent with the same `order`; omit for the first
- `limit` integer: Items per page
- `fields` string: Comma-separated fields to keep in each item, for example `id,name`; each item then carries only those fields and `id`. Omit for every field
- `order` 'oldest' | 'newest': Order of a list. oldest: the oldest item first; newest: the newest item first, for the latest items without paging through the history.

## Response `200`

Successful Response

- AutomationRunPage: One page of a list; `next_cursor` is null on the last page.
  - `items` AutomationRun[], required
    - `id` integer, required: The run; `run_start:<id>` in `list_contact_activity` is this id
    - `status` 'queued' | 'ongoing' | 'done' | 'ineligible' | 'failed', required: queued: waits to start. ongoing: running, waiting in a delay step or on hold. done: finished. ineligible: finished by being skipped. failed: finished with an error.
    - `contact_id` integer, nullable: The contact the run is for; read it with `get_contact`
    - `trigger_type` 'widget_submit' | 'manual' | 'email_click' | 'webhook' | 'segment_join' | 'shopify_order_paid' | 'shopify_order_fulfilled' | 'shopify_checkout_abandoned' | 'shopify_customer_winback' | 'shopify_customer_subscribed' | 'other': What starts the automation; `shopify_*` come from the connected Shopify store. New values may be added; strict clients must accept unknown values. `widget_submit`: a visitor submits a form of a chosen widget. `manual`: another automation, a contact import, the dashboard or `run_automation`. `email_click`: a contact clicks a link in an e-mail. `webhook`: a request to the automation's own webhook URL, or `run_automation`. `segment_join`: a contact joins a chosen segment. `shopify_order_paid`: an order is paid. `shopify_order_fulfilled`: an order is fulfilled. `shopify_checkout_abandoned`: a checkout is abandoned. `shopify_customer_winback`: a customer has not ordered for a chosen number of days. `shopify_customer_subscribed`: a customer subscribes to e-mail marketing. `other`: a trigger the dashboard does not offer.
    - `started_at` string, date-time, nullable
    - `completed_at` string, date-time, nullable: null until the run finishes
    - `error` string, nullable: Why the run failed, as the admin says it, e.g. `Email not delivered (unsubscribed)`; null unless `status` is `failed`
    - `steps` AutomationRunStep[], required: Steps the run went through, in order
      - `type` 'send_email' | 'add_tags' | 'remove_tags' | 'delay' | 'start_automation' | 'condition' | 'other', required: A step; send_email, add_tags, remove_tags and delay do what they are named for. New values may be added. start_automation: starts another automation for the contact. condition: the entry condition, in runs only. other: a step the dashboard does not offer.
      - `status` 'queued' | 'ongoing' | 'done' | 'ineligible' | 'failed', required: queued: waits to start. ongoing: running, waiting in a delay step or on hold. done: finished. ineligible: finished by being skipped. failed: finished with an error.
      - `started_at` string, date-time, required
      - `completed_at` string, date-time, nullable: null while the step goes on
      - `error` string, nullable: Why the step failed, as the admin says it; null otherwise
    - `caller` AutomationRunCaller
      - `channel` 'webhook_url' | 'ui' | 'api' | 'mcp' | 'system', required: How the run was started. webhook_url: a request to the automation's `webhook_url`; the key in the URL is the only access it needs, so the sender is not known. ui: the admin, by a user. api: the API, by an API key or an application's token. mcp: an AI assistant. system: by Getsitecontrol.
      - `client` string, nullable: The application whose token started the run, e.g. `Make` or `Zapier`, as the application named itself when it connected; null for an API key, a personal token, the admin and `webhook_url`
      - `user_id` integer, nullable: The user who started it, or whose token did; null if none
      - `api_key_id` integer, nullable: The API key that started it; null otherwise
      - `user_agent` string, nullable: `User-Agent` of the request to `webhook_url`: it may name the sending service, but the sender sets it and it is not checked; null for other channels
    - `data` object, nullable: Values the run was started with, as the sender sent them: the body sent to `webhook_url` or `data` of `run_automation`, as the steps read them in `{{$webhook.<key>}}`. A run that a "start automation" step started has the values of the run that started it. null when the run got none
    - `data_truncated` boolean, required: `data` is over 4096 bytes, so some of its keys are left out
  - `next_cursor` string, nullable

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `site_not_found`, `automation_not_found`
- `422`: Validation failed
- `429`: Rate limited
- `503`: `temporarily_unavailable`: the list took longer than 25 seconds or rate limits cannot be enforced; add filters or retry later

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)