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

# List Runs

> List runs for your workspace.

```text theme={null}
GET /v1/runs
```

List runs for your workspace with cursor-based pagination.

## Headers

| Header           | Required | Description                                                                                                                                                              |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Authorization`  | Yes      | `Bearer <api-key>`                                                                                                                                                       |
| `x-workspace-id` | No       | Only needed with OAuth/JWT tokens without an org context — with a Monid API key the workspace is bound to the key. See [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces) |

## Query Parameters

| Parameter | Type   | Default | Description                                        |
| --------- | ------ | ------- | -------------------------------------------------- |
| `limit`   | number | 10      | Maximum runs to return (1–100)                     |
| `status`  | string | —       | Filter by run status (e.g. `RUNNING`, `COMPLETED`) |
| `cursor`  | string | —       | Pagination cursor from a previous response         |

## Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.monid.ai/v1/runs?limit=10" \
    -H "Authorization: Bearer monid_live_..."
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.monid.ai/v1/runs?limit=10", {
    headers: {
      Authorization: "Bearer monid_live_...",
    },
  });
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.monid.ai/v1/runs",
      headers={
          "Authorization": "Bearer monid_live_...",
      },
      params={"limit": 10},
  )
  ```
</CodeGroup>

## 200 OK

| Field                      | Type                 | Description                                                                                             |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| `items`                    | array                | List of run summaries                                                                                   |
| `items[].runId`            | string               | Run identifier                                                                                          |
| `items[].caller`           | string               | Prefixed caller id (e.g. `USER#<userId>`)                                                               |
| `items[].provider`         | string               | Provider slug                                                                                           |
| `items[].providerName`     | string \| undefined  | Provider display name                                                                                   |
| `items[].endpoint`         | string               | Endpoint path                                                                                           |
| `items[].status`           | string               | Run status: `READY`, `RUNNING`, `STOPPING`, `COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, or `TIMED_OUT` |
| `items[].stoppable`        | boolean \| undefined | Whether the run may be stopped (non-terminal runs only)                                                 |
| `items[].providerResponse` | object \| undefined  | Provider response metadata (incl. `httpStatus`)                                                         |
| `items[].price`            | object               | Endpoint pricing (`amount` is `{ "value": number, "currency": "USD" }`)                                 |
| `items[].cost`             | object \| undefined  | Actual cost charged                                                                                     |
| `items[].billedUnits`      | number \| undefined  | Units of the price's billing unit consumed                                                              |
| `items[].resultCount`      | number \| undefined  | Deprecated alias of `billedUnits`                                                                       |
| `items[].createdAt`        | string               | ISO 8601 timestamp                                                                                      |
| `items[].startedAt`        | string \| undefined  | When execution started                                                                                  |
| `items[].completedAt`      | string \| undefined  | When execution finished                                                                                 |
| `cursor`                   | string \| null       | Next-page cursor. `null` if last page                                                                   |

### Example Response

```json theme={null}
{
  "items": [
    {
      "runId": "01HXYZ1234567890ABCDEF",
      "caller": "USER#user_abc123",
      "provider": "apify",
      "providerName": "Apify",
      "endpoint": "/apidojo/tweet-scraper",
      "status": "COMPLETED",
      "providerResponse": { "httpStatus": 200 },
      "price": { "type": "PER_CALL", "amount": { "value": 0.003, "currency": "USD" } },
      "cost": { "value": 0.003, "currency": "USD" },
      "billedUnits": 1,
      "createdAt": "2026-03-28T10:30:00.000Z",
      "startedAt": "2026-03-28T10:30:00.000Z",
      "completedAt": "2026-03-28T10:30:01.000Z"
    }
  ],
  "cursor": null
}
```