Skip to content
SonoraSonora API

List runs

GET
/workflow-runs
curl --request GET \
  --url 'https://api.usesonora.com/v1/workflow-runs?origin=auto&status=active&limit=25' \
  --header 'Authorization: Bearer <token>'

Root runs, newest first, filtered by workflow, account, person, origin, status and creation time. An unknown workflow or account is an empty page, not a 404, so a count of runs for it is 0.

Requires the workflows:read scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
workflowId
string format: uuid

A workflow’s chain root id.

accountId
string
>= 1 characters <= 255 characters

Runs about this account.

accountIdType
string

How accountId names the account (as idType on a start call); needs accountId.

contactId
string format: uuid

Runs that reached this contact.

contactEmail
string format: email

Runs that reached this address.

origin
string
Allowed values: auto manual api
status
string
Allowed values: active completed failed cancelled
createdAfter
string format: date-time
createdBefore
string format: date-time
limit
integer
default: 25 >= 1 <= 100

Page size, 1–100.

cursor
string
<= 200 characters

The previous page’s nextCursor, unchanged. Omit for the first page.

include
string

Comma-separated optional parts of the response: totalCount.

Responses

Section titled “Responses”

200

Section titled “200”

A page of runs.

Media typeapplication/json
object
data
required
Array<object>

One run as the list returns it.

object
id
required
string
status
required
string
Allowed values: active completed failed cancelled
origin
required
string
Allowed values: auto manual api
workflow
required
object
id
required

The workflow’s chain root id.

string
versionId
required

The version the run executes.

string
name
required
string | null
account
required
Any of:
object
id
required
string
name
required
string | null
recipients
required

Who an API call named and the run reaches; empty otherwise.

Array<object>

One person an API call named that the run reaches.

object
contactId
required
string | null
email
required
string
name
required

Read fresh from the contact.

string | null
matchedBy
required
Array
One of:
object
type
required
string
Allowed value: role
role
required
string
createdAt
required
string format: date-time
completedAt
required
Any of:
string format: date-time
goal
required
Any of:
object
name
required
string
status
required
string
metAt
required
Any of:
string format: date-time
windowEndsAt
required
string format: date-time
links
required
object
self
required

This resource’s canonical URL on the API host.

string
totalCount

Only with ?include=totalCount: every match under the same filters.

integer
nextCursor
required

Pass as cursor for the next page; null on the last page.

string | null
Example
{
  "data": [
    {
      "status": "active",
      "origin": "auto",
      "recipients": [
        {
          "matchedBy": [
            {
              "type": "role"
            }
          ]
        }
      ]
    }
  ]
}

400

Section titled “400”

invalid_request: A parameter or body field is missing, malformed or unknown; details.issues names each.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

401

Section titled “401”

unauthorized: The Authorization header is missing, or the key is invalid, revoked or expired.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

403

Section titled “403”

insufficient_scope: The key or token lacks the scope this endpoint needs, and details.required names it; or an OAuth access token called an endpoint only an API key can.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

429

Section titled “429”

rate_limited: Too many requests for this key; retry after Retry-After seconds.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

500

Section titled “500”

internal_error: Something went wrong on Sonora’s side. Retry, and quote requestId if it persists.

Media typeapplication/json

The one error shape every endpoint answers with.

object
error
required
object
code
required

Stable snake_case code to branch on; see the error table.

string
message
required

For humans; may change.

string
details
object
key
additional properties
requestId
required

Quote it when asking for help.

string | null
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {
      "additionalProperty": "example"
    },
    "requestId": "example"
  }
}

Try it

Run this request against your own Sonora workspace. Sign in, pick the workspace, and the page gets an access token that only reads, only what your role covers, for an hour.

GEThttps://api.usesonora.com/v1/workflow-runs

As curl

$SONORA_TOKEN is your access token or an API key; the page never shows the token.