# Get one run

Returns one run with its per-step results, so a caller can see what each step produced and where a run failed.

- Endpoint: `GET https://api.returning.ai/v1/workflow-builder/data-workflows/runs/{runId}`
- 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/get-one-run

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `workflowBuilder`

The run is read only if it belongs to the key's community, so a run id from another community answers `404 RUN_NOT_FOUND`.

| Failure | Meaning | Recovery |
| --- | --- | --- |
| `403 API_KEY_PERMISSION_DENIED` | No `workflowBuilder` | Grant the permission. |
| `404 RUN_NOT_FOUND` | Unknown run id, or a run of another community | Use a run id from `GET /{workflowId}/runs`. |

## Behaviour

Credentials in the results are replaced by the redaction marker and listed in `redactedPaths`.

The run id is enough on its own; the route is not nested under the workflow. The lookup is still scoped to the key's community.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `runId` | `string` | Yes | Run identifier: 24 hexadecimal characters. (`^[0-9a-fA-F]{24}$`) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key: `Bearer <API_KEY>`. |

### Watch for

- `results` is `null` or partial for a run that did not reach every step, so treat a missing key as "did not run", not as an empty result.
- Credentials inside a recorded result are replaced by `["__REDACTED__"]` and named in `redactedPaths`. A secret an author typed into a raw body template is returned as recorded.
- A result that came from a leaderboard outside the key's community is replaced by a redacted placeholder with the code `LEADERBOARD_NOT_FOUND`, rather than returned.
- The route works for a run of a workflow that has since been undeployed. A deleted workflow takes its runs with it.

### Example request

```bash
curl --request GET \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows/runs/<runId>' \
  --header 'Authorization: Bearer <API_KEY>'
```

### More examples

```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",
    "results": {
      "65f1a2b3c4d5e6f708192a3c": { "status": "success", "result": { "XP": 150 } },
      "65f1a2b3c4d5e6f708192a3e": { "status": "success", "result": { "branches": [{ "branchName": "XP > 100", "branchIndex": 1, "evaluation": true }, { "branchName": "Otherwise", "branchIndex": 2, "evaluation": false }] } },
      "65f1a2b3c4d5e6f708192a3d": { "status": "success", "result": { "XP": 160 } },
      "65f1a2b3c4d5e6f708192a3f": { "status": "skipped" }
    },
    "redactedPaths": []
  }
}
```

## Response

HTTP `200` with the run in `data`. `results` is an object keyed by step id, so a caller can join it to the workflow's steps:

- `results[stepId].status` is that step's outcome: `success`, `fail` or `skipped`.
- A router's result lists every branch as `{branchName, branchIndex, evaluation}`, with **1-based** `branchIndex`; the write side counts branches from `0`.
- `results[stepId].result` is what the step produced.
- A step that did not run in this execution is absent or `skipped`, depending on how the run reached it.

This is the readback for a real run: after firing a trigger, poll `GET /{workflowId}/runs` for the new run id and read it here. For a reward step, what settles it is this result plus the member's own field value, read through the platform API.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `data` | `object` | - | One run with its per-step results. |
| `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. |
| `data.results` | `object` | - | Step results keyed by step id, with credentials replaced. (Nullable) |
| `data.redactedPaths` | `string[]` | - | Credential locations replaced in this response. |

### 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",
    "results": {
      "65f1a2b3c4d5e6f708192a3c": {
        "status": "success",
        "result": {
          "Total XP": 150
        }
      },
      "65f1a2b3c4d5e6f708192a3e": {
        "status": "success",
        "result": {
          "branches": [
            {
              "branchName": "XP > 100",
              "branchIndex": 1,
              "evaluation": true
            },
            {
              "branchName": "Otherwise",
              "branchIndex": 2,
              "evaluation": false
            }
          ]
        }
      },
      "65f1a2b3c4d5e6f708192a3d": {
        "status": "success",
        "result": {
          "XP": 160
        }
      }
    },
    "redactedPaths": []
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The run id is not 24 hexadecimal characters. Use the id exactly as returned. |
| 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 | `RUN_NOT_FOUND` | Unknown run id, or a run of another community. Use a run id from the list. |

### 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 that is still `running` can gain results between two reads, so poll while the status is transient and stop when it is `success` or `error`.

## Next step

- [Retry a failed run](https://docs.returning.ai/api-reference/workflow-builder/retry-a-failed-run.md): `POST /v1/workflow-builder/data-workflows/runs/{runId}/retry`.