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 an in-progress 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 — one of `pending`, `running`, `completed`, `failed`, `needs_review`, `cancelled`, `paused`. An unrecognised value returns 400 `invalid_status`.

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 run record — status, progress, timing, a roll-up summary, per-state item_counts, 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. The list endpoint above returns the same shape minus output_files (omitted so listing many runs doesn't mint a signed URL per file).

Response shapeJSON

{
  "run_id": "abfcbeef-6d3a-4ab3-aca7-516cbff72d01",
  "agent_id": "agt_01HAKZ...",
  "status": "completed",
  "progress_percent": 100.0,
  "started_at": "2026-05-26T11:42:19Z",
  "completed_at": "2026-05-26T11:43:07Z",
  "duration_seconds": 48.0,
  "trigger_type": "event",
  "error": null,
  "summary": { "total_processed": 100, "successful": 95, "failed": 3, "exceptions": 2, "skipped": 0 },
  "item_counts": { "completed": 95, "failed": 3, "needs_review": 2, "total": 100 },
  "output_files": [
    {
      "filename": "report.pdf",
      "content_type": "application/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`, `pending`	`paused`
`resume`	`paused`, `needs_review`, `running`	`running`
`cancel`	`running`, `pending`, `needs_review`, `paused`	`cancelled`
`retry`	`failed`	Re-runs the same run from the failed step

An action against an incompatible state returns 409 invalid_state_transition. 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.