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

# routines runs list

> List recent async routine runs and their statuses.

List recent async routine runs in the workspace, with status and progress counters.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay routines runs list [--limit <n>] [--cursor <token>]
```

Results are paginated. `--limit` sets the page size, and the response includes a top-level `cursor` when more runs are available; pass it back with `--cursor` to fetch the next page.

## Flags

| Flag               | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| `--limit <n>`      | Maximum runs to return per page. Must be a positive integer up to 100. Defaults to 20. |
| `--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": [
    {
      "routineRunId": "run_abc123",
      "routineId": "function:t_abc123",
      "status": "in_progress",
      "total": 100,
      "finished": 42
    }
  ],
  "cursor": "next_page_token"
}
```

| Field                 | Type                                                 | Description                                                                                  |
| --------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `data[].routineRunId` | string                                               | Run id. Pass to [`clay routines runs get`](/cli/reference/routines-runs-get).                |
| `data[].routineId`    | string                                               | The routine that was run.                                                                    |
| `data[].status`       | `"in_progress" \| "complete" \| "validation_failed"` | Current run status.                                                                          |
| `data[].total`        | number                                               | Total items in the run.                                                                      |
| `data[].finished`     | number                                               | Items that have finished so far.                                                             |
| `cursor`              | string                                               | Present when more runs are available. Pass it back via `--cursor`. Omitted on the last page. |

## Errors

| Code               | Exit | Notes                                               |
| ------------------ | ---- | --------------------------------------------------- |
| `validation_error` | 2    | `--limit` is not a positive integer or exceeds 100. |
| `auth_forbidden`   | 3    | The API key lacks the `cli:all` scope (or `all`).   |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay routines runs list
clay routines runs list --limit 10 | jq -r '.data[].routineRunId'
clay routines runs list --limit 10 --cursor "$CURSOR"
clay routines runs list | jq '.data[] | select(.status == "in_progress")'
```