---
title: runs_list
description: Free, cursor-paginated run history for a workspace, filtered by status or job, with bounded summary rows by default.
---

<WorksIn />

Cursor-paginated run history filtered by workspace, status, or capability. Free and read-only.
Each row is a bounded summary, not the full result payload; pass `includeResult: true` to get
full run records back without calling [`runs_get`](/mcp-tools/runs-get) on each one.

## Inputs

| Argument | Type | Required | Default | Limits | Meaning |
| --- | --- | --- | --- | --- | --- |
| `status` | string | No | - | `queued`, `running`, `completed`, `failed`, `blocked`, `stopped`, `reconciliation_pending`, `pending_provider` | Filter by run status. |
| `capability` | string | No | - | pattern `^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)+$` | Filter by job id. |
| `limit` | integer | No | 20 | 1-50 | Rows per page. |
| `cursor` | string | No | - | - | From a previous answer's `nextCursor`. |
| `includeResult` | boolean | No | - | - | Return full run records, including `result`, in place of the bounded summary. |

Each row has `runId`, `endpointId`, `providerId`, `status`, `providerResponseStatus`,
`createdAt`, `completedAt`, `actualCost`, `error` (same shape as [`run`](/mcp-tools/run)/`runs_get`),
`resultBytes`, and `servedEndpointId`/[`servedProviderId`](/concepts/served-provider) (absent when none did).

## Example call

```json
{
  "status": "completed",
  "limit": 5
}
```

## Example answer

Abridged: a full row also carries `providerResponseStatus`, `resultBytes` and, on a fallback
run, `servedEndpointId`/`servedProviderId`.

```json
{
  "nextCursor": "run_91f95b26366f480382ebdff27e77f7e8",
  "runs": [
    {
      "runId": "run_06d5d0b1fe0847b48002ead80e3da7df",
      "endpointId": "linkup-search",
      "providerId": "linkup",
      "status": "completed",
      "createdAt": "2026-09-24T21:09:03.737Z",
      "completedAt": "2026-09-24T21:09:10.916938+00:00",
      "actualCost": 0.005,
      "error": null
    }
  ]
}
```

## Errors

Free and read-only; no `runs.execute` needed. A `status` outside the enum returns
[`validation_error`](/errors/rest-errors#validation_error) naming every accepted value. `limit` above 50 or below 1 is refused the same
way.

## REST and CLI

- REST: [`GET /v1/runs`](/reference/runs/get-v1-runs)
- CLI: `looot runs list [--status] [--limit] [--cursor]`

<Related />