# List the runs of a workflow

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

- Endpoint: `GET https://api.returning.ai/v1/workflow-builder/data-workflows/{workflowId}/runs`
- Section: Workflow Builder / Runs
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `workflowBuilder`
- Retries: Safe to retry: it writes nothing.
- Guide: generated from the published specification
- Last updated: 28 Oct 2026
- Web page: https://docs.returning.ai/api-reference/workflow-builder/list-the-runs-of-a-workflow

## 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.

| Failure | Meaning | Recovery |
| --- | --- | --- |
| `403 API_KEY_PERMISSION_DENIED` | No `workflowBuilder` | Grant the permission. |
| `404 WORKFLOW_NOT_FOUND` | Unknown id, or another community's workflow | Use 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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | `string` | Yes | Workflow identifier: 24 hexadecimal characters, as returned in `_id`. (`^[0-9a-fA-F]{24}$`) |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Page number, from `1`. (Min 1; default `1`) |
| `limit` | `integer` | No | Page size, at most `100`. A larger value is refused with `400 VALIDATION_FAILED`, never silently reduced. (Default 20; max 100) |
| `status` | `string` | No | Keep only runs in this state: `success`, `running`, `error`, `queued` or `unknown`. (`success`, `running`, `error`, `queued`, `unknown`) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key: `Bearer <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`.

### Example request

```bash
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>'
```

### More examples

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 }
}
```

## 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.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | - | Runs of this page. |
| `data._id` | `string` | - | Run identifier. |
| `data.workflowId` | `string` | - | Workflow that ran. |
| `data.communityId` | `string` | - | Community of the workflow. |
| `data.status` | `string` | - | `success`, `error`, `running`, `queued` or `unknown`. |
| `data.startTime` | `string` | - | Start time, when recorded. |
| `data.endTime` | `string` | - | Finish time, when recorded. |
| `data.createdAt` | `string` | - | Record creation time. |
| `data.updatedAt` | `string` | - | Last change to the record. |
| `meta` | `object` | - | Paging metadata. |
| `meta.page` | `integer` | - | - |
| `meta.limit` | `integer` | - | - |
| `meta.total` | `integer` | - | - |
| `meta.totalPages` | `integer` | - | - |

### Example response (200)

```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
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | `limit` above `100`, a non-numeric `page`, or an unknown `status`. Fix the query value. |
| 401 | `AUTHENTICATION_REQUIRED` | No key, or an unknown key. Send a valid key. |
| 401 | `API_KEY_REQUIRED` | A valid admin session was used, because this API accepts community API keys only. Use a community API key. |
| 403 | `API_KEY_PERMISSION_DENIED` | No `workflowBuilder`. Grant the permission. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | `WORKFLOW_NOT_FOUND` | Unknown id, or another community's workflow. Use an id from this community. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 429 | `RATE_LIMITED` | The community's API rate limit was reached. Wait for the window to reset, then retry. |
| 500 | `INTERNAL_ERROR` | 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.

## Next step

- [Get one run](https://docs.returning.ai/api-reference/workflow-builder/get-one-run.md): `GET /v1/workflow-builder/data-workflows/runs/{runId}`.