List automation runs
const url = 'https://api.getsitecontrol.com/v1/sites/1/automations/1/runs?limit=50&order=oldest';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.getsitecontrol.com/v1/sites/1/automations/1/runs?limit=50&order=oldest' \ --header 'Authorization: Bearer <token>'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) or why runs failed
(status=failed). 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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Automation id from list_automations
Automation id from list_automations
Query Parameters
Section titled “Query Parameters”Only runs of this contact, id from list_contacts
Only runs of this contact, id from list_contacts
Only runs in this status
Only runs in this status
Only runs started at or after this moment; without an offset, taken as UTC; a plain date means its start
Only runs started at or after this moment; without an offset, taken as UTC; a plain date means its start
next_cursor of the previous page, sent with the same order; omit for the first
next_cursor of the previous page, sent with the same order; omit for the first
Items per page
Items per page
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
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 of the items: oldest first (default) or newest first; asc and desc mean the same
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Responses
Section titled “Responses”One page of a list; next_cursor is null on the last page.
object
object
The run; run_start:<id> in list_contact_activity is this id
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.
The contact the run is for; read it with get_contact
What started the run; null when not recorded
Null until the run finishes
Why the run failed, as the admin says it, e.g. Email not delivered (unsubscribed); null unless status is failed
Steps the run went through, in order
object
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.
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.
Null while the step goes on
Why the step failed, as the admin says it; null otherwise
{ "items": [ { "status": "queued", "trigger_type": "widget_submit", "steps": [ { "type": "send_email", "status": "queued" } ] } ]}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
temporarily_unavailable: the list took longer than 25 seconds or rate limits cannot be enforced; add filters or retry later
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds