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);fieldnames the first invalid field,details.fieldsevery 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): RunscreatedAt(string (date-time)): When the run startederror(NodeError)attempt(integer): Attempt the error happened incode(string): Stable error codedetails(object): Further facts of the errormessage(string): Human-readable messagenode(string): Id of the node that failed
finishedAt(string (date-time)): When the run ended; absent while runningflowId(string (uuid)): Id of the flowflowKey(string): Key of the flowflowName(string): Name of the flowid(string (uuid)): Run idstartedBy(string): Who or what started the runstatus(string): State of the run (one ofrunning,succeeded,failed,cancelled)steps(integer): Node activations so fartestMode(string): A test run of a draft (dry: writes simulated); absent for a normal run (one ofdry,live)trigger(string): The trigger's idtriggerKind(string): Kind of the trigger that started the run (one ofevent,schedule,manual,webhook)
nextCursor(string): Cursor of the next page; absent on the last page
Example 200 answer:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/runs' \
-H "Authorization: Bearer $ACCESS_TOKEN"