> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valendata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# list-workflow-runs

> Retrieve the 50 most recent runs for a specific Workflow, ordered by most recent first, including status, outputs, credits, and per-step results.

`GET /api/workflows/{workflow_id}/runs` returns the execution history for a single Workflow: status, outputs, credits charged, and per-step results for each run. Results are capped at the 50 most recent runs, ordered by `created_at` descending.

## Endpoint

```text theme={null}
GET https://api.valendata.com/api/workflows/{workflow_id}/runs
```

## Authentication

This endpoint requires a session token:

```http theme={null}
Authorization: Bearer YOUR_SESSION_TOKEN
```

## Path Parameters

<ParamField path="workflow_id" type="string" required>
  The UUID of the Workflow whose run history you want to retrieve.
</ParamField>

## Example Request

```bash theme={null}
curl https://api.valendata.com/api/workflows/3f2a1bc4-e89b-12d3-a456-426614174000/runs \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
```

## Response

Returns a flat JSON array of up to 50 `WorkflowRun` objects, most recent first.

### WorkflowRun Object

<ResponseField name="id" type="string">
  Unique identifier for this run (plain UUID).
</ResponseField>

<ResponseField name="workflow_id" type="string">
  UUID of the Workflow that was executed.
</ResponseField>

<ResponseField name="status" type="string">
  `completed`, `failed`, or `waiting_for_human`.
</ResponseField>

<ResponseField name="inputs" type="object | null">
  The inputs passed into the first step of this run.
</ResponseField>

<ResponseField name="outputs" type="any | null">
  Output from the final step. `null` if the run failed.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the run failed, otherwise `null`.
</ResponseField>

<ResponseField name="credits_charged" type="float">
  Credits consumed across all steps in this run.
</ResponseField>

<ResponseField name="execution_time_ms" type="integer | null">
  Total wall-clock time in milliseconds.
</ResponseField>

<ResponseField name="started_at" type="string | null">
  ISO 8601 UTC timestamp of when execution began.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  ISO 8601 UTC timestamp of when the run finished.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 UTC timestamp of when the run record was created.
</ResponseField>

<ResponseField name="step_results" type="array">
  Ordered step result objects. See the [step result fields on POST /workflows/run](/api-reference/workflows/run) for the full field list.
</ResponseField>

### Example Response

```json theme={null}
[
  {
    "id": "a1b2c3d4-0001-0000-0000-000000000000",
    "workflow_id": "3f2a1bc4-e89b-12d3-a456-426614174000",
    "status": "completed",
    "inputs": { "target_url": "https://example.com/pricing" },
    "outputs": [{ "plan": "Pro", "price_usd": 80 }],
    "error": null,
    "credits_charged": 12.5,
    "execution_time_ms": 18400,
    "started_at": "2026-08-20T09:00:00Z",
    "completed_at": "2026-08-20T09:00:18Z",
    "created_at": "2026-08-20T09:00:00Z",
    "step_results": []
  }
]
```

## Error Handling

| HTTP Status | Meaning                                            |
| :---------- | :------------------------------------------------- |
| `401`       | Session token missing or expired.                  |
| `404`       | Workflow not found or you don't have access to it. |
| `500`       | Internal error on Valendata's side.                |