> ## 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 Agent Run

> Get status and outputs for a run.

Poll this endpoint to check the status of your agent run and retrieve outputs.

## Request

```bash theme={null}
curl -X GET "https://api.mosaic.so/agent_run/[run_id]" \
  -H "Authorization: Bearer mk_your_api_key"
```

## Response

```json theme={null}
{
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "started_at": "2025-01-10T14:30:00Z",
  "status": "completed",
  "status_message": null,
  "needs_credits": false,
  "errors": [],
  "node_status_counts": {
    "completed": 10,
    "in_progress": 0,
    "failed": 0
  },
  "inputs": [
    {
      "video_url": "https://storage.googleapis.com/mosaic-inputs/...",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-inputs/..."
    }
  ],
  "outputs": [
    {
      "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "video_url": "https://storage.googleapis.com/mosaic-outputs/...",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-thumbnails/...",
      "premiere_prproj_url": "https://storage.googleapis.com/mosaic-outputs/.../timeline.zip?...",
      "sources": [
        {
          "provider": "getty",
          "source_kind": "licensed_library",
          "media_type": "image",
          "provider_asset_id": "1234567890",
          "render_asset_id": "getty_image_000",
          "query": "mayor press conference",
          "title": "Mayor speaks at press conference",
          "credit": "Photographer / Collection",
          "source_url": "https://www.gettyimages.com/detail/...",
          "display_url": "https://media.gettyimages.com/...",
          "rights_status": "licensed",
          "start_ms": 1200,
          "end_ms": 3400,
          "start_seconds": 1.2,
          "end_seconds": 3.4,
          "placement": "partial_screen",
          "layout": "bottom",
          "getty_asset_family": "editorial",
          "source_metadata": {},
          "rights_metadata": {}
        }
      ],
      "completed_at": "2025-01-10T14:35:30Z",
      "original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8"
    }
  ]
}
```

## Output Fields

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Unique identifier for this output render |
| `video_url` | `string` | Signed URL to download the rendered video (valid for 7 days) |
| `thumbnail_url` | `string \| null` | Signed URL to download the video thumbnail |
| `premiere_prproj_url` | `string \| null` | Signed URL to download the Premiere Pro timeline zip attached to this render (when available) |
| `sources` | `array` | Source citations for licensed or external media used in this output. Getty b-roll citations include timing, query, asset IDs when resolved, placement, and rights metadata. |
| `completed_at` | `string` | ISO 8601 timestamp when this output finished rendering |
| `original_node_id` | `string \| null` | Template agent\_node\_id this output originated from. Use this to map outputs to specific nodes in your agent. |

<Tip>
  **Tracking outputs**: Use `original_node_id` to identify which node in your agent template produced each output. This allows you to consistently map outputs to your application logic across multiple runs.
</Tip>

## Source Fields

| Field | Type | Description |
| - | - | - |
| `provider` | `string` | Source provider, for example `getty`. |
| `media_type` | `string` | `image`, `video`, or another media type. |
| `provider_asset_id` | `string \| null` | Provider asset ID, such as the Getty image/video ID, when resolved. |
| `render_asset_id` | `string \| null` | Internal render/timeline asset ID. |
| `query` | `string \| null` | Search query used to choose the source. |
| `start_ms` / `end_ms` | `number \| null` | Usage window in the rendered output. |
| `placement` / `layout` | `string \| null` | How the media was placed, such as `full_screen`, `partial_screen`, `top`, or `bottom`. |
| `source_metadata` / `rights_metadata` | `object` | Provider-specific metadata and rights details when available. |

## Run Fields

| Field | Type | Description |
| - | - | - |
| `agent_id` | `string` | Agent UUID that started this run. |
| `status` | `string` | Overall run status (see Status Values below). |
| `status_message` | `string \| null` | Human-readable detail about the run status. |
| `needs_credits` | `boolean` | `true` when one or more runtime tasks in this run are marked `needs_credits=true` (insufficient credits). |
| `errors` | `array` | Error messages grouped by template node. Each entry has `original_node_id` and `messages[]`. Empty array `[]` when the run has no errors. |
| `node_status_counts` | `object` | Counts of nodes in `completed`, `in_progress`, and `failed` states. |

For node-level statuses, error details, and credit-blocked details, use [Get Agent Run Nodes](/api/agent-runs/get-agent-run-nodes).

<Tip>
  If `needs_credits` is `true`, first check `GET /plan`. If no paid plan is active, choose one via `GET /plan/list` and `POST /plan/upgrade` (complete checkout when `requires_checkout: true`). You can then enable auto top-ups with `POST /credits/settings` if your active plan is `creator`, `creator_annual`, `professional`, or `professional_annual`, and finally call [Resume Agent Run](/api/agent-runs/post-agent-run-resume) to re-queue failed/blocked runtime nodes in the same run.
</Tip>

## Status Values

| Status | Description |
| - | - |
| `running` | Agent is processing your videos |
| `completed` | Processing finished successfully |
| `partial_complete` | Some outputs finished successfully, but others failed |
| `failed` | The entire run failed, no outputs generated |
| `cancelled` | The run was cancelled by the user |


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