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