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

# workflows runs list

> List runs of a workflow, newest first, with optional filters.

List the runs of a workflow, newest first. Filter by status, creation time, snapshot version, or a free-text search over run inputs, outputs, and error. Use [`clay workflows runs get`](/cli/reference/workflows-runs-get) to inspect a single run.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay workflows runs list <workflowId> [--status <status>] [--created-after <datetime>] [--snapshot-id <id>] [--search <text>] [--limit <n>] [--cursor <token>]
```

## Arguments

| Argument     | Description                              |
| ------------ | ---------------------------------------- |
| `workflowId` | Workflow id, e.g. `wf_abc123`. Required. |

## Flags

| Flag                         | Description                                                           |
| ---------------------------- | --------------------------------------------------------------------- |
| `--status <status>`          | Filter by run status. Repeatable to match any of several statuses.    |
| `--created-after <datetime>` | Only runs created at or after this datetime.                          |
| `--snapshot-id <id>`         | Only runs of this workflow snapshot version.                          |
| `--search <text>`            | Case-insensitive text search over run inputs, outputs, and error.     |
| `--limit <n>`                | Page size, 1–100. Defaults to the server page size (50) when omitted. |
| `--cursor <token>`           | Resume from a previous response's `cursor` to fetch the next page.    |

## Output

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "runId": "wfr_xyz789",
      "workflowId": "wf_abc123",
      "workflowName": "Lead enrichment",
      "status": "completed",
      "createdAt": "2026-06-01T00:00:00Z",
      "updatedAt": "2026-06-01T00:04:10Z",
      "workflowSnapshotId": "wfs_123",
      "batchId": "batch_123",
      "triggerId": "trg_123"
    }
  ],
  "cursor": "next_page_token"
}
```

| Field                       | Type           | Description                                                                     |
| --------------------------- | -------------- | ------------------------------------------------------------------------------- |
| `data[].runId`              | string         | Run id. Pass to [`clay workflows runs get`](/cli/reference/workflows-runs-get). |
| `data[].workflowId`         | string         | Workflow the run belongs to.                                                    |
| `data[].workflowName`       | string \| null | Workflow display name, or `null`.                                               |
| `data[].status`             | string         | Run status. See the status values below.                                        |
| `data[].createdAt`          | string         | When the run was created.                                                       |
| `data[].updatedAt`          | string         | When the run was last updated.                                                  |
| `data[].workflowSnapshotId` | string         | Snapshot version the run executed.                                              |
| `data[].batchId`            | string         | Present when the run is part of a batch.                                        |
| `data[].triggerId`          | string         | Present when the run was started by a trigger.                                  |
| `cursor`                    | string         | Present when more runs are available. Pass it back via `--cursor`.              |

Run `status` is one of: `pending` (queued but not yet started), `running` (actively executing nodes), `waiting` (blocked on an async operation or concurrency slot), `paused` (paused by an operator — resume to continue), `completed` (finished successfully), or `failed` (terminated with an error).

## Errors

| Code               | Exit | Notes                                                                                                      |
| ------------------ | ---- | ---------------------------------------------------------------------------------------------------------- |
| `validation_error` | 2    | `--status` is not a known status, `--created-after` is not a valid datetime, or `--limit` is out of range. |
| `not_found`        | 6    | No workflow with that id.                                                                                  |
| `auth_forbidden`   | 3    | The API key lacks the `terracotta:cli` scope.                                                              |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay workflows runs list wf_abc123 | jq -r '.data[].runId'
clay workflows runs list wf_abc123 --status failed
clay workflows runs list wf_abc123 --status failed --status completed
clay workflows runs list wf_abc123 --created-after 2026-06-01T00:00:00Z --search clay.com
clay workflows runs list wf_abc123 --limit 100 | jq -r '.data[].runId'
clay workflows runs list wf_abc123 --cursor "$CURSOR" | jq -r '.cursor'
```