Runs

Endpoints for workflow runs under /api/v1/runs.

Endpoints

Run status

A run's status is one of:

Listing runs

GET /api/v1/runs accepts these query params (all optional):

Returns { runs[], links[] }, where each links entry carries run, execution, status, rerun, and cancel URLs. The ordinary listing has no cursor — raise limit (at most 200) to fetch more, and narrow it with the filters above. Only the delegation lookup below is paged by a cursor; sending cursor without delegationRef answers 400 with run_cursor_requires_delegation_ref.

Find a run by delegation

GET /api/v1/runs?delegationRef=<ref> returns the runs (newest queued first, the run ID breaking ties) that were started with productContext.delegationRef equal to ref, in the same { runs[], links[] } shape and projection, plus a nextCursor. Use it to reconcile when your product lost the response of execute. A delegation reference is not unique: your product may reuse one for any number of runs, and every one of them stays reachable. A page holds at most limit runs (clamped 1–200; the default is 20 here instead of 100), and nextCursor is an opaque string, or null when no run is left. Send it back unchanged as cursor, with the same delegationRef, filters, limit, workspace and API key, to get the next page; a cursor used with another lookup or key answers 400 run_cursor_invalid. Cursor requests are authenticated, so callers cannot move the keyset boundary by editing its contents. For runs that remain available and match the request, following the cursor returns each run that existed when the traversal started exactly once. The order is fixed when a run is queued, so a run queued during the traversal can sort before the current cursor and be missed. After reaching a null cursor, restart the lookup from the first page to pick up runs queued during the previous traversal. status, trigger, workflowId, level, dateFrom, dateTo and query narrow the match. When they leave few runs among many, a page can hold fewer than limit runs, even none, while nextCursor is still set: keep following it until it is null. The order cannot be changed, so a sort other than newest answers 400 with run_delegation_sort_unsupported, and a cursor that is not a nextCursor this API issued answers 400 with run_cursor_invalid. The lookup is limited to the key's workspace: a reference used in another workspace returns { runs: [], nextCursor: null }. A malformed reference answers 400 with product_context_delegation_ref_invalid. The run object never includes the product context itself. A run whose end user was erased loses its productContext and its delegationRef, so the lookup no longer finds it.

A product gateway key with the run permission may use this lookup to recover runs started by its product. It must send a valid delegationRef; its results include only end-user runs from workflows on that key's allowlist that were started by that same API key. Another gateway key cannot read them, even when its workflow allowlist overlaps. Gateway keys cannot use the unfiltered run listing. Workspace keys keep the workspace-wide delegation lookup described above.

Signed callbacks when a run ends

A run started with a registered callbackUrl (see execute) is reported to your product with a signed run.completed callback when it reaches succeeded, failed or canceled: the run ID, workflow and version, the status, a summary of the output, connectionRequired and the delegationRef of its productContext. A run parked at a wait sends nothing until it ends. Delivery is retried with backoff for about two hours; a callback that never arrives is recovered by reading the run here, by ID or by delegationRef, with a workspace API key. A product gateway key can recover a run by delegationRef with its run permission, but reads individual runs through /api/v1/end-users/runs/{id} instead. The full contract is in Product connections.

Safe read projection

Workspace keys with workspace.secret.read or workspace.write receive the complete run object. Personal, Copilot, Viewer, organization-derived, and oversight reads receive the stable workspace-safe.v1 projection instead. Its redaction object is:

{
  "applied": true,
  "projection": "safe-content",
  "contractVersion": "workspace-safe.v1",
  "restrictedFields": [
    "input",
    "output",
    "error",
    "steps.input",
    "steps.output",
    "steps.metadata",
    "steps.error",
    "logs"
  ]
}

The safe run contains id, workspaceId, workflowId, optional versionId, workflowName, trigger, status, timestamps, optional durationMs, costCredits, and step identity/status/timing. Live destination runs also retain executionTarget with targetId, kind, name, activationId and generation. Simulations retain simulationTargetId when a destination was selected. These fields distinguish Production from previews even when the reader cannot inspect execution payloads. It omits run and step inputs, outputs and errors, step metadata, logs, active waits, and execution snapshots. Clients must branch on redaction.applied; an omitted field is restricted, not an empty value.

For complete run readers, a step may include metadata.resolvedCredentials, an array of account names and their resolution source (node or destination, with destinationName for a destination binding). This records the credential resolved for that execution, including failed steps, without secret values. It is separate from step output and does not enter rerun inputs. Older runs and simulated steps may omit this metadata.

Single run and actions

GET /api/v1/runs/{id} returns { run, links } using the same projection rules as the list. POST /api/v1/runs/{id}/cancel cancels a queued/running run (returns 409 otherwise). POST /api/v1/runs/{id}/rerun starts a fresh run from the original input and returns 201 with { run, statusUrl, cancelUrl, links }. Both actions accept an Idempotency-Key header.

Through the API, a run made for an end user of your product can be re-run only by the product gateway key that started it (with the X-End-User-Id header). Another product gateway key, or another end user, gets 404, as on the End users API; an ordinary workspace key gets 403. In the app, only an explicit workspace Admin or Owner can re-run it; other members get 403. A run whose end user was erased cannot be re-run (409). Product gateway keys poll and cancel through /api/v1/end-users/runs/{id} instead of these routes. See End users.

Next steps