---
title: "List agent runs"
method: GET
path: "/agent/{agent_id}/runs"
tags: ["Agents"]
---

# List agent runs

`GET /agent/{agent_id}/runs`

## Request

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

List recent runs for an agent with optional filtering.

## Path parameters

- `agent_id` string, required

## Query parameters

- `status` string
- `from` string, date-time
- `to` string, date-time
- `limit` integer
- `cursor` string, date-time
- `folder_id` string
- `batch_id` string
- `batch_key` string
- `storage_trigger_id` string
- `production_id` string

## Response `200`

Agent runs retrieved successfully

- AgentRunsResponse
  - `runs` AgentRunSummary[]
    - `run_id` string
    - `agent_id` string
    - `status` 'running' | 'completed' | 'failed' | 'partial_complete' | 'cancelled'
    - `status_message` string, nullable
    - `started_at` string, date-time
    - `updated_at` string, date-time
    - `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[]
      - `video_url` string: URL of the input video
      - `thumbnail_url` string, nullable: URL of the input video thumbnail
    - `outputs` AgentOutput[]
      - `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.
    - `triggered_by` union: Standard trigger metadata exposed as `triggered_by` in run APIs and webhooks. Google Drive triggers use the storage trigger shape with `type: "storage_trigger"` and `provider: "google_drive"`.
      - YouTubeTriggerInfo
        - `type` 'youtube', required
        - `channel_id` string, nullable: YouTube channel ID when available.
        - `video_id` string, required: YouTube video ID that triggered the run.
        - `video_title` string, required: Title of the triggering YouTube video.
        - `video_url` string, uri, required: Canonical YouTube URL for the triggering video.
        - `triggered_at` string, date-time, required: When Mosaic created the trigger context.
        - `trigger_id` string, nullable: Trigger subscription ID when the run came from a saved YouTube trigger. `null` for manual API runs started from a YouTube URL.
        - `target_video_input_agent_node_id` string, nullable: Template Video Input node targeted by this run when the trigger fans out to multiple inputs.
      - StorageTriggerInfo
        - `type` 'storage_trigger', required
        - `provider` 'google_drive' | 'aws_s3' | 's3', required: Trigger source provider. Google Drive trigger runs use `google_drive`; `s3` is accepted for legacy rows.
        - `storage_trigger_subscription_id` string: Internal storage trigger subscription ID used to associate runs with the configured trigger.
        - `batch_window_id` string: Internal batch window ID used to group runs created from the same trigger flush.
        - `drive_paths` string[]: Canonical Google Drive paths for all files included in this run.
        - `triggered_at` string, date-time, required: When Mosaic created the storage-trigger run.
  - `next_cursor` string, date-time, nullable: Pagination cursor for the next page

## Other responses

- `401`: Authentication failed
- `403`: Access denied
- `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)