---
title: "Run an agent"
method: POST
path: "/agent/{agent_id}/run"
tags: ["Agents"]
---

# Run an agent

`POST /agent/{agent_id}/run`

## Request

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

Execute an agent workflow. Supports standard video-input workflows and generation-only workflows (AI Avatar, Video Generation, Audio Generation, or Image Generation). Canonical input model is `video_inputs` (per Video Input tile). Top-level input arrays (`video_ids`, `node_render_ids`, `video_urls`) are shorthand for single-input runs. Do not mix top-level input arrays with `video_inputs` in the same request.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `video_inputs` object[]: Canonical per-tile input mapping. Each entry must include `agent_node_id` and at least one of `video_ids`, `node_render_ids`, or `video_urls`. Required for multi-input runs.
    - `agent_node_id` string, required: Template Video Input `agent_node_id` from GET /agent/{agent_id}.
    - `video_ids` string[]
    - `node_render_ids` string[]
    - `video_urls` string[]
  - `video_ids` string[]: Top-level shorthand for single-input runs. Video UUIDs from the Uploads API (or existing workspace video assets).
  - `node_render_ids` string[]: Top-level shorthand for single-input runs. Completed agent_node_render IDs from prior run outputs (`GET /agent_run/{run_id}` -> `outputs[].id`) or run webhooks.
  - `video_urls` string[]: Top-level shorthand for single-input runs. Video URLs to ingest (including YouTube and signed HTTP/HTTPS URLs). YouTube videos max 5 hours, signed URLs max 5 hours / 5 GB per input.
  - `callback_url` string, uri: Optional webhook URL for status updates
  - `update_params` object: Optional parameters to override node parameters in the agent workflow. Key is agent_node_id, value is parameter object. Parameters are validated against each node's schema; invalid node IDs/values return 400 and the run is not created.
  - `ignore_nodes` string[]: Optional list of agent_node_id values to bypass for this run. Ignored nodes are removed from the runtime graph and their incoming edges are rewired directly to their downstream nodes.

## Response `200`

Agent run started successfully

- object
  - `run_id` string: Unique identifier for this agent run

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `413`: Payload too large

---

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