Endpoints · 03

Run management.

Six endpoints to operate workflow runs from outside Studio — list them, fetch one, pause, resume, retry, or cancel. All authenticated with the same Access Key as triggers.

Workflow only

These routes are workflow-only. Conversational agents have no runs, so these endpoints return 400 runtime_not_applicable for them.

Endpoints

Method	Path	Purpose
GET	`/api/agents/{agent_id}/runs`	List runs for an agent
GET	`/api/agents/{agent_id}/runs/{run_id}`	Fetch one run with signed output URLs
POST	`/api/agents/{agent_id}/runs/{run_id}/cancel`	Cancel a queued or running run
POST	`/api/agents/{agent_id}/runs/{run_id}/pause`	Pause a running run
POST	`/api/agents/{agent_id}/runs/{run_id}/retry`	Retry a failed run with the same inputs
POST	`/api/agents/{agent_id}/runs/{run_id}/resume`	Resume a paused run

List runs

GET /api/agents/{agent_id}/runs

Query parameters

Name	Type	Description
`limit`	`integer`	Max runs to return. Defaults to the runtime's own default.
`status`	`string`	Filter by run state — e.g. `queued`, `running`, `succeeded`, `failed`, `paused`, `cancelled`.

Any other query parameters are ignored.

List runs · cURLshell

curl "https://webhook.olbrain.com/api/agents/agt_01HAKZ.../runs?limit=20&status=failed" \
  -H "Authorization: Bearer ak_<your-access-key>"

Fetch one run

GET /api/agents/{agent_id}/runs/{run_id}

Returns the full run record — status, timing, inputs, step results, and any output files. Output files come back as output_files[], each with a V4 signed HTTPS URL valid for 15 minutes after the GET. Re-issue the GET to get fresh URLs.

Response shapeJSON

{
  "run_id": "run_01HZQ7K9...",
  "workflow_id": "agt_01HAKZ...",
  "status": "succeeded",
  "started_at": "2026-05-26T11:42:19Z",
  "completed_at": "2026-05-26T11:43:07Z",
  "inputs": { "...": "..." },
  "output_files": [
    {
      "name": "report.pdf",
      "size_bytes": 184320,
      "url": "https://storage.googleapis.com/...",
      "url_expires_at": "2026-05-26T12:00:00Z"
    }
  ]
}

Control endpoints

The four control endpoints share the same shape: POST with an empty body, optionally supply ?triggered_by= to attribute the action in audit logs.

POST /api/agents/{agent_id}/runs/{run_id}/cancel

POST /api/agents/{agent_id}/runs/{run_id}/pause

POST /api/agents/{agent_id}/runs/{run_id}/retry

POST /api/agents/{agent_id}/runs/{run_id}/resume

Query parameters

Name	Type	Description
`triggered_by`	`string`	Optional. Attribution string that appears on the run's audit trail (e.g. `shopify-webhook-handler`, `ops-dashboard`).

State transitions

Action	Allowed from	Transitions to
`pause`	`running`	`paused`
`resume`	`paused`	`running`
`cancel`	`queued`, `running`, `paused`	`cancelled`
`retry`	`failed`, `cancelled`	New run with copied inputs

An action against an incompatible state returns 409. Re-fetch the run to see its current state before retrying.

Cancel a runcURL

curl -X POST "https://webhook.olbrain.com/api/agents/agt_01HAKZ.../runs/run_01HZQ7K9.../cancel?triggered_by=ops-dashboard" \
  -H "Authorization: Bearer ak_<your-access-key>"

Scope

A run can only be read or controlled via the agent it belongs to. Calling a run-management route with the wrong agent_id in the URL returns 404.