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

# Get Run Progress

> Read whole-run tile counts plus one bounded page of tiles, each with at most five recent tasks. Counts and completed_node_percent cover the entire run, not only the page. Use tasks for complete task evidence. Progress is not an ETA.

Required scope: `agent_runs:read`. See [API key permissions](/api/api-key-scopes) and the [pipeline dashboard guide](/api/observability/overview).

## Request

```bash theme={null}
curl "https://api.mosaic.so/agent_run/44444444-4444-4444-8444-444444444444/progress?limit=1" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "X-Workspace-Id: 66666666-6666-4666-8666-666666666666"
```

Workspace IDs and resource IDs above are examples. Use IDs returned by your own API calls.

## Parameters

| Parameter | Location | Meaning |
| - | - | - |
| `limit` | query | Page size from 1 to 100; default 25. Progress and notification configuration pages count tiles. |
| `cursor` | query | Opaque next\_cursor from the previous page. Pass verbatim and preserve the original filters. Do not decode or construct it. |
| `from` | query | Inclusive ISO 8601 lower bound on creation time. |
| `to` | query | Inclusive ISO 8601 upper bound on creation time. |
| `updated_from` | query | Inclusive ISO 8601 update watermark. Restart pagination on each poll and fetch every page before advancing it. |
| `workspace_id` | query | Optional workspace UUID within the key organization. Must match X-Workspace-Id when both are supplied. |
| `run_id` | path | run id UUID. |
| `X-Workspace-Id` | header | Restrict requests to an authorized workspace UUID. Omit to query the organization. |

## Response example

```json theme={null}
{
  "run_id": "44444444-4444-4444-8444-444444444444",
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "status": "running",
  "status_message": null,
  "started_at": "2026-10-15T12:00:00Z",
  "updated_at": "2026-10-15T12:01:00Z",
  "triggered_by": {
    "source_folder_id": "drive-folder-7",
    "batch_window_id": "33333333-3333-4333-8333-333333333333",
    "storage_trigger_subscription_id": "22222222-2222-4222-8222-222222222222"
  },
  "node_status_counts": {
    "total": 40,
    "completed": 10,
    "running": 1,
    "not_started": 29,
    "in_progress": 0,
    "failed": 0,
    "cancelled": 0,
    "skipped": 0
  },
  "completed_node_percent": 25,
  "nodes": [
    {
      "node_id": "55555555-5555-4555-8555-555555555555",
      "original_node_id": null,
      "node_type_id": "11111111-1111-4111-8111-111111111111",
      "name": "Reframe",
      "status": "running",
      "status_message": null,
      "updated_at": "2026-10-15T12:01:00Z",
      "needs_credits": true,
      "tasks": [
        {
          "task_id": "99999999-9999-4999-8999-999999999999",
          "status": "running",
          "progress_percent": 40,
          "needs_credits": true,
          "error_message": null,
          "created_at": "2026-10-15T12:00:00Z",
          "updated_at": "2026-10-15T12:01:00Z",
          "heartbeat_at": "2026-10-15T12:01:00Z",
          "heartbeat_age_seconds": 15
        }
      ]
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNVQxMjowMDowMFoiLCJpZCI6IjU1NTU1NTU1LTU1NTUtNDU1NS04NTU1LTU1NTU1NTU1NTU1NSJ9",
  "tasks_snapshot_limit": 5
}
```

## Tile and task values

| Field | Meaning |
| - | - |
| `run_id` | Run ID. |
| `agent_id` | Originating agent. |
| `status` | Persisted run status. |
| `status_message` | Run status details. |
| `started_at` | Run creation time. |
| `updated_at` | Run-row update time; not a watermark for all tile/task changes. |
| `triggered_by` | Source metadata used to start this run. |
| `node_status_counts` | Counts for the entire run, independent of node pagination. Includes total, completed, in\_progress, failed, cancelled, skipped, not\_started, and other persisted statuses such as running. |
| `completed_node_percent` | Rounded completed tiles / all tiles × 100. Not elapsed-time progress or an ETA; failures/skips may prevent 100. |
| `nodes` | One cursor page of runtime tiles, default 25 and maximum 100. |
| `next_cursor` | Pass verbatim to fetch the next node page; null when finished. |
| `tasks_snapshot_limit` | Maximum embedded tasks per tile. |

When `next_cursor` is non-null, request the next page with the same filters and that cursor. `limit` defaults to 25 and is capped at 100. Read the [polling and error-handling guidance](/api/observability/overview#poll-without-losing-updates) before building a dashboard.


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