Runs
Trigger, inspect, cancel, and re-run workflow executions via the API.
Endpoints for workflow runs under /api/v1/runs.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/runs | List runs |
| GET | /api/v1/runs/{id} | Get a run |
| POST | /api/v1/runs/{id}/cancel | Cancel a run |
| POST | /api/v1/runs/{id}/rerun | Re-run a run |
Run status
A run's status is one of:
| Status | Terminal? | Meaning |
|---|---|---|
queued | No | Accepted, waiting for a worker |
running | No | Executing |
waiting | No | Durably paused (timer, approval, or event) — will resume later |
succeeded | Yes | Completed successfully |
failed | Yes | Ended with an error |
canceled | Yes | Canceled before completion |
Listing runs
GET /api/v1/runs accepts these query params (all optional):
| Param | Description |
|---|---|
status | Filter by run status (including waiting) |
trigger | manual | webhook | schedule | copilot | api |
workflowId | Restrict to one workflow |
level | Log level filter |
dateFrom, dateTo | ISO date range |
query | Free-text search across run metadata |
sort | Sort key |
limit | Max results, default 100, clamped 1–200 |
Returns { runs[], links[] }, where each links entry carries run, execution, status,
rerun, and cancel URLs. There is no cursor pagination — raise limit to fetch more.
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.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, logs, active waits, and execution snapshots. Clients
must branch on redaction.applied; an omitted field is restricted, not an empty value.
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.