## Get a run with its node history (tenant:flows:read|write|admin; a scoped flow's run with the owning module's view)

`GET /api/flows/v1/runs/{id}`

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

The run, the YAML of the version it ran, and per node its input, output, attempts and error. The run of a
scoped flow is answered to whoever its module lets view the scope (`404` otherwise, `503 scope_unavailable`
when the module cannot answer).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The run (`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`)
- **404** The record does not exist in the token's tenant – or it belongs to a scope the caller may not view (a scoped flow stays hidden). (`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:

- `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`)
- `activations` (array of Activation): Every node execution of the run
  - `attempt` (integer): Number of the current or last attempt
  - `attempts` (array of object): Every failed attempt (at
  - `createdAt` (string (date-time)): When the node was reached
  - `dueAt` (string (date-time)): The next attempt of a node waiting for a retry
  - `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 node ended
  - `handled` (boolean): An error port took the failure over
  - `id` (string (uuid)): Activation id
  - `input` (object): Resolved parameters; error on an error path
  - `kind` (string): The node kind, e.g. `action`, `if`, `human_task`
  - `nodeId` (string): The node's id in the definition
  - `output` (any): The node's output
  - `outputSize` (integer): Size of the output in bytes
  - `port` (string): The port the node left on
  - `scopeKey` (string): The loop iteration: empty at the top, "each[2]", nested "a[0]/b[1]"
  - `startedAt` (string (date-time)): When the node started running
  - `state` (object): A parking node's working state (a foreach's items and results, a sub-flow's child run)
  - `status` (string): skipped: no path reached the node (one of `pending`, `running`, `waiting`, `succeeded`, `failed`, `cancelled`, `skipped`)
- `cancelledBy` (string): E-mail of who cancelled the run
- `definition` (string): The YAML of the version the run ran
- `output` (any): The output of the run's end node
- `timeoutAt` (string (date-time)): When the run times out
- `triggerData` (object): The data the run started with (`trigger.data`)
- `vars` (object): The run's variables
- `version` (integer): Number of the published version the run is pinned to

Example 200 answer:

```json
{
  "activations": [
    {
      "attempt": 1,
      "createdAt": "2026-11-18T07:59:02Z",
      "finishedAt": "2026-11-18T07:59:03Z",
      "id": "1d3f5a7b-9c2e-4a4b-8d6f-0a2c4e6a8b1d",
      "input": {
        "ref": "4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e"
      },
      "kind": "action",
      "nodeId": "ticket",
      "outputSize": 1834,
      "port": "success",
      "startedAt": "2026-11-18T07:59:02Z",
      "status": "succeeded"
    },
    {
      "attempt": 1,
      "createdAt": "2026-11-18T07:59:03Z",
      "finishedAt": "2026-11-18T07:59:04Z",
      "id": "3f5a7b9c-1e4a-4b6d-8f0a-2c4e6a8b0d3f",
      "input": {
        "subject": "Kritisches Ticket SUP-214",
        "to": [
          "person:jonas.bauer@muster-it.example"
        ]
      },
      "kind": "mail",
      "nodeId": "info",
      "output": {
        "sent": 1
      },
      "outputSize": 12,
      "port": "success",
      "startedAt": "2026-11-18T07:59:03Z",
      "status": "succeeded"
    }
  ],
  "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",
  "triggerData": {
    "itemId": "4e6a8c0b-2d4f-4a1b-9c3e-5f7a9b1c3d5e",
    "number": "SUP-214",
    "priority": "hoch",
    "title": "WLAN im Restaurant fällt aus"
  },
  "triggerKind": "event",
  "vars": {},
  "version": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
