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

# List Pipeline Runs

> Discover runs with bounded lightweight pages, without loading graphs, inputs, outputs, or per-run tile evidence.

Required scope: `agent_runs:read`. Prefer this endpoint for large [pipeline dashboards](/api/observability/overview); load progress/tasks only for runs you need to inspect.

```bash theme={null}
curl "https://api.mosaic.so/pipeline_runs?folder_id=drive-folder-7&status=running&limit=25" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "X-Workspace-Id: 66666666-6666-4666-8666-666666666666"
```

## Parameters

| Parameter | Meaning |
| - | - |
| `limit` | Integer 1–100; default 25. |
| `cursor` | Previous `next_cursor`, passed verbatim with unchanged filters. |
| `workspace_id` | Workspace UUID within your organization; must match `X-Workspace-Id` if both are supplied. |
| `agent_id` | Agent UUID. |
| `status` | One exact persisted status, for example `running` or `completed`. |
| `from`, `to` | Inclusive ISO 8601 bounds on run creation time. |
| `updated_from` | Inclusive run-row update watermark. Tile/task changes are tracked separately. |
| `folder_id` | Exact `trigger_info.source_folder_id` provider folder ID. |
| `batch_id` | Exact `trigger_info.batch_window_id` batch UUID. |
| `batch_key` | Exact persisted batch grouping key. |
| `storage_trigger_id` | Exact `trigger_info.storage_trigger_subscription_id` UUID. |
| `production_id` | Exact persisted production ID. |

Filters can be combined. Runs without matching source metadata are excluded. Use IDs returned by your own API calls; the UUIDs below are examples.

## Response example

```json theme={null}
{
  "runs": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "agent_id": "11111111-1111-4111-8111-111111111111",
      "workspace_id": "66666666-6666-4666-8666-666666666666",
      "status": "running",
      "status_message": null,
      "created_at": "2026-10-15T12:00:00Z",
      "updated_at": "2026-10-15T12:01:00Z",
      "trigger_info": {
        "source_folder_id": "drive-folder-7",
        "batch_window_id": "33333333-3333-4333-8333-333333333333"
      }
    }
  ],
  "next_cursor": null
}
```

`id` is the run UUID; pass it as `run_id` to [progress](/api/observability/get-run-progress), [tasks](/api/observability/list-run-tasks), or [delivery receipts](/api/observability/list-notification-deliveries). `status_message` provides persisted status details. `updated_at` may be null for historical rows whose update time is unknown. `trigger_info` may be null for manually started runs. `agent_id` may be null if the originating agent is unavailable.

Fetch every `next_cursor` until null. On subsequent polls, restart without a cursor and overlap your `updated_from` watermark. See [polling and error handling](/api/observability/overview#poll-without-losing-updates). A missing permission returns a structured `403` naming `agent_runs:read`; retrying with the same key cannot grant access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.