---
title: "Get Run Progress"
method: GET
path: "/agent_run/{run_id}/progress"
tags: ["Pipeline Observability"]
---

# Get Run Progress

`GET /agent_run/{run_id}/progress`

## Request

- Base URL: `https://api.mosaic.so`
- URL: `https://api.mosaic.so/agent_run/{run_id}/progress`
- Auth: HTTP bearer

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.

## Path parameters

- `run_id` string, uuid, required

## Query parameters

- `limit` integer
- `cursor` string
- `from` string, date-time
- `to` string, date-time
- `updated_from` string, date-time
- `workspace_id` string, uuid

## Headers

- `X-Workspace-Id` string, uuid

## Response `200`

Current organization-scoped evidence.

- CanvasRunProgress
  - `run_id` string, uuid, required: Run ID.
  - `agent_id` string, uuid, nullable, required: Originating agent.
  - `status` string, required: Persisted run status.
  - `status_message` string, nullable, required: Run status details.
  - `started_at` string, date-time, required: Run creation time.
  - `updated_at` string, date-time, nullable, required: Run-row update time; not a watermark for all tile/task changes.
  - `triggered_by` object, nullable, required: Source metadata used to start this run.
  - `node_status_counts` object, required: 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` integer, required: Rounded completed tiles / all tiles × 100. Not elapsed-time progress or an ETA; failures/skips may prevent 100.
  - `nodes` CanvasProgressNode[], required: One cursor page of runtime tiles, default 25 and maximum 100.
    - `node_id` string, uuid, required: Runtime tile ID; use for task/notification node_id filters.
    - `original_node_id` string, uuid, nullable, required: Original template tile ID, when recorded.
    - `node_type_id` string, uuid, nullable, required: Tile type ID.
    - `name` string, nullable, required: Tile type display name.
    - `status` string, required: Persisted runtime tile status.
    - `status_message` string, nullable, required: Tile status details.
    - `updated_at` string, date-time, required: Tile row update time.
    - `needs_credits` boolean, required: True if any attached task for this tile needs credits, including tasks outside the snapshot.
    - `tasks` CanvasProgressTask[], required: At most five recent attached tasks per tile. Page the tasks endpoint for complete history.
      - `task_id` string, uuid, required: Task ID. Use the tasks endpoint for the complete task list.
      - `status` string, nullable, required: Persisted task status.
      - `progress_percent` number, nullable, required: Task progress clamped to 0–100; null when unreported.
      - `needs_credits` boolean, required: Task credit wait flag.
      - `error_message` string, nullable, required: Task error details.
      - `created_at` string, date-time, required: Task creation time.
      - `updated_at` string, date-time, nullable, required: Task update time.
      - `heartbeat_at` string, date-time, nullable, required: Last worker heartbeat.
      - `heartbeat_age_seconds` integer, nullable, required: Elapsed seconds since heartbeat. A missing/stale heartbeat is evidence to investigate, not a definitive failure.
  - `next_cursor` string, nullable, required: Pass verbatim to fetch the next node page; null when finished.
  - `tasks_snapshot_limit` 5, required: Maximum embedded tasks per tile.

## Other responses

- `400`: Invalid UUID, cursor, limit, timestamp, filter, or unsupported updated_from on batch items.
- `401`: Missing, invalid, or revoked API key.
- `403`: Insufficient API key scope, unavailable paid-plan access, or workspace header/query mismatch. Scope errors include code, required_scope, granted_scopes, retryable, and resolution. Other authorization errors retain detail.
- `404`: Requested run, trigger, or batch is absent or outside the authorized organization/workspace.
- `500`: Database or query failure. Never interpret this as an empty successful result; use bounded backoff.

---

[API](https://skmtc.dev/mosaic/apis/mosaic-ai-api.md) - [All operations](https://skmtc.dev/mosaic/apis/mosaic-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mosaic/apis/mosaic-ai-api/revisions/c20e9fc606a4?raw)