ConnectCloud Developers

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:

{
  "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"

View as Markdown · Interactive reference · OpenAPI