Skip to content
SonoraSonora API

Get a run

GET
/workflow-runs/{runId}
curl --request GET \
  --url https://api.usesonora.com/v1/workflow-runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

One run: its trigger, steps, what it is waiting on, and every email it produced with per-recipient engagement. A fan-out branch’s id or a private workflow’s run is 404.

Requires the workflows:read scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
runId
required
string format: uuid

Responses

Section titled “Responses”

200

Section titled “200”

The run.

Media typeapplication/json

One run: its trigger, steps, what it is waiting on, and every email it produced.

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
trigger
required
Any of:

What the API call that started a run asked for, and who it skipped.

object
requestId
required
string
receivedAt
required
string format: date-time
account
required
object
id
required
string
idType
required
string
roles
required

The roles the call matched, as slugs.

Array<string>
variables
required
object
key
additional properties
string | number | boolean
idempotencyKey
required
string | null
skippedRecipients
required
Array<object>

A person the call named who won’t be emailed.

object
contactId
string
email
string
reason
required
string
Allowed values: unsubscribed bounced do_not_contact no_email recently_triggered
matchedBy
required
Array
One of:
object
type
required
string
Allowed value: role
role
required
string
lastRunId

recently_triggered only: the run that last reached them through this workflow.

string
retryAfter

recently_triggered only: when the resend window lets a call reach them again.

string
currentStep
required
Any of:
object
id
required
string
label
required
string
waitingOn
required
Any of:
string
Allowed values: review send reply delay enrichment
error
required
string | null
steps
required
Array<object>
object
runId
required

The run that took the step: the root, or one fan-out branch.

string
id
required
string
label
required
string
type
required
string | null
status
required
string
outcome
required
string | null
error
required
string | null
enteredAt
required
string format: date-time
endedAt
required
Any of:
string format: date-time
messages
required
Array<object>

One email a run produced, per recipient once it has gone out.

object
stepId
required
string
stepLabel
required
string
cueId
required
string
contactId
required
string | null
email
required
string | null
status
required
string
Allowed values: draft held sent bounced not_sent
heldUntil
required
Any of:
string format: date-time
note
required

Why a send reached fewer people than it addressed, or nobody.

string | null
sentAt
required
Any of:
string format: date-time
trackingScope
required
Any of:
string
Allowed values: recipient email
firstOpenedAt
required
Any of:
string format: date-time
openCount
required
integer
firstClickedAt
required
Any of:
string format: date-time
clickCount
required
integer
firstRepliedAt
required
Any of:
string format: date-time
replyCount
required
integer
firstBouncedAt
required
Any of:
string format: date-time
Example
{
  "status": "active",
  "origin": "auto",
  "recipients": [
    {
      "matchedBy": [
        {
          "type": "role"
        }
      ]
    }
  ],
  "trigger": {
    "skippedRecipients": [
      {
        "reason": "unsubscribed",
        "matchedBy": [
          {
            "type": "role"
          }
        ]
      }
    ]
  },
  "waitingOn": "review",
  "messages": [
    {
      "status": "draft",
      "trackingScope": "recipient"
    }
  ]
}

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

404

Section titled “404”

run_not_found: No workflow run with that id.

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/{runId}

As curl

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