# Runs

> The Runs operations of the Hub REST API (3 operations).

URL: https://docs.synap.live/docs/reference/hub-api/runs · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /runs

List runs across flows (unified feed)

Newest-first run feed across automation / playbook / capture / capability / session / chat. Filter to one ledger with flowType, or one flow with flowId. This is the AI/CLI diagnose door: a capture run's activity (via GET /runs/{id}) is its correlationId-keyed decision + trace events — what happened and why.

Responses:

- `200`: Run feed
- `403`: Forbidden

## GET /runs/{id}

Get one run + its activity timeline

Returns the run and its flow-agnostic activity: automation steps, or a capture's decision/trace events (component/reason/fixHint — the diagnose story). Requires flowType (the id space differs per ledger).

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `flowType` | query | "automation" \| "playbook" \| "capture" \| "capability" \| "session" \| "chat" | yes |  |

Responses:

- `200`: Run detail
- `403`: Forbidden
- `404`: Run not found

## POST /diagnose

Diagnose — whole-pod health, a class surface, an object, or an agent

The THIRD door (alongside ask + capture): mode is derived from payload shape, not a caller-chosen endpoint. {} → whole-pod health · {type} → a diagnosable class as a surface · {id} → auto-detect the object's kind and explain its state + why · {agentId} → agent behavioural scorecard · {runId,flowType} / {flowType,flowId} → today's run-detail/run-feed grammar.

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `agentId` | string |  |  |
| `id` | string |  |  |
| `type` | "proposal" \| "session" \| "capability" \| "agent" \| "entity" \| "run" \| "workspace" |  |  |
| `workspaceId` | string \| null |  |  |
| `stuckThresholdHours` | number |  |  |
| `flowType` | "automation" \| "playbook" \| "capture" \| "capability" \| "session" \| "chat" |  |  |
| `flowId` | string |  |  |
| `runId` | string |  |  |
| `limit` | number |  |  |

Responses:

- `200`: Diagnose result
- `403`: Forbidden