## List the runs the caller may see (tenant:flows:read|write|admin; a scoped flow's runs with the owning module's view)

`GET /api/flows/v1/runs`

Module: Flows · operationId: `listFlowRuns` · Tag: Runs · Auth: access token (`Authorization: Bearer <accessToken>`)

Runs of tenant flows for every flows permission; runs of personal flows only for their owner. Newest first.
The runs of a scoped flow are listed only with its `flowId`, for whoever its module lets view the scope (an
empty list otherwise, `503 scope_unavailable` when the module cannot answer); without `flowId` the list holds
runs of flows without scope only.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `flowId` | query | string (uuid) |  |  |
| `status` | query | string |  | (one of `running`, `succeeded`, `failed`, `cancelled`) |
| `limit` | query | integer |  | (default `50`; max 200) |
| `cursor` | query | string |  | nextCursor of the previous page |

### Responses

- **200** Runs (`application/json`)
- **400** Invalid input (`invalid`); `field` names the first invalid field, `details.fields` every one. (`application/json`)
- **401** Missing, invalid or expired token (no body).
- **403** The token lacks the permission or has no active tenant (`forbidden`). Also: `person_required` (a service-account key on personal flows or the task inbox), `live_test_forbidden`, `forbidden_grant`, `starter_excluded`. (`application/json`)
- **503** A dependency is not available: `scope_unavailable` (the module that owns a flow's scope did not answer who may see and manage it – nothing of a scoped flow is shown or changed), `identity_unavailable` (HR), `ai_unavailable`, `ai_failed`. (`application/json`)

Fields of the 200 answer:

- `items` (array of RunSummary, required): Runs
  - `createdAt` (string (date-time)): When the run started
  - `error` (NodeError)
    - `attempt` (integer): Attempt the error happened in
    - `code` (string): Stable error code
    - `details` (object): Further facts of the error
    - `message` (string): Human-readable message
    - `node` (string): Id of the node that failed
  - `finishedAt` (string (date-time)): When the run ended; absent while running
  - `flowId` (string (uuid)): Id of the flow
  - `flowKey` (string): Key of the flow
  - `flowName` (string): Name of the flow
  - `id` (string (uuid)): Run id
  - `startedBy` (string): Who or what started the run
  - `status` (string): State of the run (one of `running`, `succeeded`, `failed`, `cancelled`)
  - `steps` (integer): Node activations so far
  - `testMode` (string): A test run of a draft (dry: writes simulated); absent for a normal run (one of `dry`, `live`)
  - `trigger` (string): The trigger's id
  - `triggerKind` (string): Kind of the trigger that started the run (one of `event`, `schedule`, `manual`, `webhook`)
- `nextCursor` (string): Cursor of the next page; absent on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-18T07:59:02Z",
      "finishedAt": "2026-11-18T07:59:04Z",
      "flowId": "6f2a9c4e-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
      "flowKey": "kritische-tickets-zusammenfassen",
      "flowName": "Kritische Tickets zusammenfassen",
      "id": "9a1b3c5d-7e2f-4a6b-8c0d-1e3f5a7b9c2d",
      "startedBy": "event desk.item.created",
      "status": "succeeded",
      "steps": 2,
      "trigger": "neues_ticket",
      "triggerKind": "event"
    },
    {
      "createdAt": "2026-11-16T07:00:01Z",
      "error": {
        "attempt": 3,
        "code": "module_error",
        "message": "crm antwortete mit 503 (Dienst nicht erreichbar).",
        "node": "offene"
      },
      "finishedAt": "2026-11-16T07:04:12Z",
      "flowId": "0e2a4c6e-8b1d-4f3a-9c5e-7b9d1f3a5c7e",
      "flowKey": "offene-chancen-montag",
      "flowName": "Offene Chancen zum Wochenstart",
      "id": "1b3d5f7a-9c1e-4a3b-8d5f-7a9c1e3b5d7f",
      "startedBy": "schedule",
      "status": "failed",
      "steps": 1,
      "trigger": "montags",
      "triggerKind": "schedule"
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0xMS0xNlQwNzowMDowMVoiLCJpZCI6IjFiM2Q1ZjdhIn0"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
