Returning.AIDocs
v1

API reference / Workflow Builder

.md

List the runs of a workflow

Lists the runs of one workflow, newest first, with an optional status filter and paging.

Last updated 28 Oct 2026API v1

Method
GET
Path
https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}/runs
Permission
workflowBuilder
Retries
Safe to retry: it writes nothing.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
workflowBuilder

Authorization: Bearer <API_KEY> with workflowBuilder, on a workflow of the key's community. Runs are scoped to the workflow and to the community, so this route cannot be used to read another community's runs.

FailureMeaningRecovery
403 API_KEY_PERMISSION_DENIEDNo workflowBuilderGrant the permission.
404 WORKFLOW_NOT_FOUNDUnknown id, or another community's workflowUse an id from this community.

Behaviour#

A run is one execution of the workflow, whether it was started by a trigger or by a live test.

The list carries no step results, so it never carries member data. Read one run with GET /runs/{runId} for the per-step results.

Request#

Path parameters#

workflowId#stringREQUIRED
Workflow identifier: 24 hexadecimal characters, as returned in _id.

Rule^[0-9a-fA-F]{24}$

Eg65f1a2b3c4d5e6f708192a3b

Query parameters#

page#integerOPTIONAL
Page number, from 1.

RuleMin 1; default 1

Eg1

limit#integerOPTIONAL
Page size, at most 100. A larger value is refused with 400 VALIDATION_FAILED, never silently reduced.

RuleDefault 20; max 100

Eg20

status#stringOPTIONAL
Keep only runs in this state: success, running, error, queued or unknown.

Rulesuccess, running, error, queued, unknown

Egsuccess

Headers#

Authorization#stringREQUIRED
Community API key: Bearer <API_KEY>.

EgBearer <API_KEY>

Watch for

  • A run's status is the workflow's outcome, not the outcome of every step. A workflow can be success while a step was skipped, and an error run can still have applied some steps. Read the run detail for the step results.
  • running and queued are transient. Poll with a bounded interval instead of a fixed sleep.
  • The list has no step results, no member identifiers and no trigger payload. Those arrive with GET /runs/{runId}, redacted.
  • A run created by a live whole-workflow test is removed after the test, so it does not appear here.
  • A previously deleted workflow takes its runs with it: this route then answers 404.
More examples and details

A populated page:

JSON
{
  "data": [
    {
      "_id": "65f1a2b3c4d5e6f708192a40",
      "workflowId": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "status": "success",
      "startTime": "2026-10-24T10:02:14.000Z",
      "endTime": "2026-10-24T10:02:19.000Z",
      "createdAt": "2026-10-24T10:02:13.000Z",
      "updatedAt": "2026-10-24T10:02:19.000Z"
    },
    {
      "_id": "65f1a2b3c4d5e6f708192a45",
      "workflowId": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "status": "error",
      "startTime": "2026-10-24T09:44:02.000Z",
      "endTime": "2026-10-24T09:44:05.000Z",
      "createdAt": "2026-10-24T09:44:01.000Z",
      "updatedAt": "2026-10-24T09:44:05.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
}

A workflow that has never run returns an empty page with 200, not an error:

JSON
{
  "data": [],
  "meta": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 }
}

curl --request GET \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/<workflowId>/runs?page=1&limit=20&status=success' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

HTTP 200 with data (an array of run summaries) and meta (page, limit, total, totalPages).

status is one of success, error, running, queued or unknown. startTime and endTime are present when the run reached those points. The list is the readback that proves a deploy, a live test or a retried run actually executed.

Paging is by page number, ordered newest first, with the identifier as a tie-break. totalPages is 0 when there are no runs.

data#object[]
Runs of this page.

Eg[ ... ]

_id#string
Run identifier.

Eg"65f1a2b3c4d5e6f708192a40"

workflowId#string
Workflow that ran.

Eg"65f1a2b3c4d5e6f708192a3b"

communityId#string
Community of the workflow.

Eg"65f1a2b3c4d5e6f708192a50"

status#string
success, error, running, queued or unknown.

Eg"success"

startTime#string
Start time, when recorded.

Eg"2026-10-24T10:02:14.000Z"

endTime#string
Finish time, when recorded.

Eg"2026-10-24T10:02:19.000Z"

createdAt#string
Record creation time.

Eg"2026-10-24T10:02:13.000Z"

updatedAt#string
Last change to the record.

Eg"2026-10-24T10:02:19.000Z"

meta#object
Paging metadata.

Eg{"page": 1, "limit": 20, "total": 2, "totalPages": 1}

page#integer

Eg1

limit#integer

Eg20

total#integer

Eg2

totalPages#integer

Eg1

{
  "data": [
    {
      "_id": "65f1a2b3c4d5e6f708192a40",
      "workflowId": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "status": "success",
      "startTime": "2026-10-24T10:02:14.000Z",
      "endTime": "2026-10-24T10:02:19.000Z",
      "createdAt": "2026-10-24T10:02:13.000Z",
      "updatedAt": "2026-10-24T10:02:19.000Z"
    },
    {
      "_id": "65f1a2b3c4d5e6f708192a45",
      "workflowId": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "status": "error",
      "startTime": "2026-10-24T09:44:02.000Z",
      "endTime": "2026-10-24T09:44:05.000Z",
      "createdAt": "2026-10-24T09:44:01.000Z",
      "updatedAt": "2026-10-24T09:44:05.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Errors#

Fix the request04

400VALIDATION_FAILEDFix the request
limit above 100, a non-numeric page, or an unknown status. Fix the query value.
401AUTHENTICATION_REQUIREDFix the request
No key, or an unknown key. Send a valid key.
401API_KEY_REQUIREDFix the request
A valid admin session was used, because this API accepts community API keys only. Use a community API key.
403API_KEY_PERMISSION_DENIEDFix the request
No workflowBuilder. Grant the permission.

Fix the data01

404WORKFLOW_NOT_FOUNDFix the data
Unknown id, or another community's workflow. Use an id from this community.

Retry with backoff02

429RATE_LIMITEDRetry with backoff
The community's API rate limit was reached. Wait for the window to reset, then retry.
500INTERNAL_ERRORRetry with backoff
Unexpected failure. Retry with bounded backoff.

Retries

Safe to retry: it writes nothing. A run can finish between two calls, so a retry can show a run moving from running to success in place. Treat a page as a snapshot and poll for a specific run id rather than comparing whole pages.

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED",
    "errors": [
      {
        "path": "params.workflowId",
        "message": "Id must be a 24 character hex string"
      }
    ],
    "requestId": "3f4d0e8b-7a6c-4f1e-9b2d-5a7c8e1f0a3b"
  },
  "message": "API request rejected error.",
  "detail": "The request body is not valid.",
  "solution": "Read error detail and try again."
}

Next step#

Get one runGET/v1/workflow-builder/data-workflows/runs/{runId}