---
title: "Get agent run status"
method: GET
path: "/agent_run/{run_id}"
tags: ["Agents"]
---

# Get agent run status

`GET /agent_run/{run_id}`

## Request

- Base URL: `https://api.mosaic.so`
- URL: `https://api.mosaic.so/agent_run/{run_id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Retrieve the current status, credit-blocked state (`needs_credits`), and outputs of an agent run.

## Path parameters

- `run_id` string, required

## Response `200`

Agent run status retrieved successfully

- AgentRunStatus
  - `agent_id` string: ID of the agent that started this run.
  - `started_at` string, date-time: When the agent run started
  - `status` 'running' | 'completed' | 'failed' | 'partial_complete' | 'cancelled': Current status of the agent run
  - `status_message` string, nullable: Optional message providing details about the current status
  - `needs_credits` boolean: True when one or more runtime tasks in this run are marked `needs_credits=true` (insufficient credits).
  - `node_status_counts` NodeStatusCounts
    - `completed` integer: Number of nodes that finished successfully (completed, partial_complete)
    - `in_progress` integer: Number of nodes currently processing or waiting (running, queued)
    - `failed` integer: Number of nodes that failed or are blocked (failed, blocked)
  - `inputs` VideoInput[]: Array of input videos
    - `video_url` string: URL of the input video
    - `thumbnail_url` string, nullable: URL of the input video thumbnail
  - `outputs` AgentOutput[]: Array of output videos
    - `id` string: Unique identifier for this output render
    - `video_url` string, nullable: Signed URL to download the output video (valid for 7 days). Null if render failed.
    - `thumbnail_url` string, nullable: Signed URL for the video thumbnail (valid for 7 days)
    - `premiere_prproj_url` string, nullable: Signed URL to download the Premiere Pro timeline package zip attached to this render (when available).
    - `sources` RenderSource[]: Source citations for licensed or external media used in this output. Getty b-roll sources include timing, query, asset IDs when resolved, placement, and rights metadata.
      - `provider` string: Source provider. Getty sources use `getty`.
      - `source_kind` string: Source category, for example `licensed_library`.
      - `media_type` string: Media type such as `image` or `video`.
      - `provider_asset_id` string, nullable: Provider asset ID, such as the Getty image/video ID, when resolved.
      - `render_asset_id` string, nullable: Internal render/timeline asset ID for this source usage.
      - `query` string, nullable: Search query used to choose the source.
      - `title` string, nullable
      - `credit` string, nullable
      - `source_url` string, nullable
      - `display_url` string, nullable
      - `rights_status` string: Known rights status, for example `licensed`, `restricted`, or `unknown`.
      - `start_ms` number, nullable: Start timestamp of the source usage in the rendered output.
      - `end_ms` number, nullable: End timestamp of the source usage in the rendered output.
      - `start_seconds` number, nullable
      - `end_seconds` number, nullable
      - `placement` string, nullable: Placement chosen by the editor, such as `full_screen` or `partial_screen`.
      - `layout` string, nullable: Layout region, such as `top`, `bottom`, or `full`.
      - `getty_asset_family` string, nullable: Getty asset family, such as `editorial` or `creative`.
      - `source_metadata` object
      - `rights_metadata` object
    - `completed_at` string, date-time: ISO 8601 timestamp when this output finished rendering
    - `original_node_id` string, nullable: Template agent_node_id this output originated from. Use this to map outputs to specific nodes in your agent.
  - `errors` object[]: Error messages grouped by template node. Empty array when the run has no errors.
    - `original_node_id` string, nullable, required: Template agent_node_id these errors originated from
    - `messages` string[], required: List of error messages from failed tasks in this node

## Other responses

- `401`: Authentication failed
- `404`: Resource not found

---

[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)