Runs

Auth: API key. Scopes: runs:read / runs:write

Base path: /v1/runs

A run is one execution of a care pathway, identified by its runId. That same id is the run’s pathway instance. Its sourceId points back to the blueprint it was copied from (Diagrams). For the values automationStatus can take, see Automation status.

Runs are created by firing a trigger, not by POSTing here. To start one, fire a web trigger (POST /v1/triggers/:triggerId). Search and schedule triggers, and webhook events, also create runs. This page covers reading and managing a run once it exists.

Get a run

GET /v1/runs/:runId

{
  "runId": "<uuid>",
  "sourceId": "<uuid>",
  "triggerId": "<uuid>",
  "idempotencyKey": "<string> | null",
  "automationStatus": "<AutomationStatus>",
  "createdAt": "<ISO 8601>",
  "updatedAt": "<ISO 8601>",
  "error": {
    "message": "<string>",
    "nodeId": "<string>"
  } | null
}

automationStatus moves from queued to scheduled to running, and then to a terminal value. See Automation status. The error object is present only when the run has errored, and is null otherwise.

List runs

GET /v1/runs

Query	Description
`triggerId`	Filter to runs started from one trigger
`idempotencyKey`	Filter to runs created from one idempotent request, a trigger fire or a webhook delivery
`status`	Filter by automation status
`limit`	Max results (default `25`, max `100`)
`cursor`	Pagination cursor

To find everything a single webhook delivery or trigger fire produced, pass the idempotencyKey you sent with it: GET /v1/runs?idempotencyKey=…. A delivery can start more than one run, so this returns a list.

Start a queued run

POST /v1/runs/:runId/start

This is the API equivalent of pressing play: it starts a queued run so an automation worker can pick it up, moving it to scheduled. It works only while the run is queued, and any other state returns 409. The call is audited as run.start.

Cancel

POST /v1/runs/:runId/cancel

Sets the run’s automationStatus to canceled, and is audited as run.cancel.

Pause

POST /v1/runs/:runId/pause

Sets the run’s automationStatus to paused, and is audited as run.pause.

Resume

POST /v1/runs/:runId/resume

Returns a paused run to running, and is audited as run.resume.

Aggregate status

GET /v1/triggers/:triggerId/status

Counts are scoped to one trigger.

{
  "queued": <integer>,
  "scheduled": <integer>,
  "running": <integer>,
  "paused": <integer>,
  "completed": <integer>,
  "errored": <integer>,
  "canceled": <integer>,
  "stopped": <integer>,
  "recentRuns": [
    {
      "runId": "<uuid>",
      "name": "<string>",
      "automationStatus": "<AutomationStatus>",
      "createdAt": "<ISO 8601>"
    }
  ]
}