Skip to main content
POST
/
agent
/
{agent_id}
/
run
Run Agent
curl --request POST \
  --url https://api.example.com/agent/{agent_id}/run
Execute an agent workflow. Supports standard video-input workflows and AI-only workflows (AI Content Generation or AI Avatar).

​
Standard Workflows

For workflows starting with a Video Input node, provide at least one of: video_urls, video_ids, or node_render_ids. For URL inputs, the backend automatically detects URL type, downloads the video, and runs the workflow. 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "video_urls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'

​
AI-Only Workflows

For workflows starting with AI Content Generation or AI Avatar nodes (and no Video Input node), no video inputs should be provided. These agents generate video content based on the parameters configured in the agent. 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-webhook.com/callback",
    "update_params": {
      "NODE_ID": {
        "prompt": "A futuristic city in the style of cyberpunk"
      }
    }
  }'

​
Parameters

FieldTypeRequiredDescription
video_urlsstring[]ConditionalArray of video URLs to process. Required if the agent has a video input node. Supports YouTube URLs and signed URLs (HTTP/HTTPS).
node_render_idsstring[]Optional list of completed render IDs from prior runs/webhooks. Use this to chain outputs from one Mosaic run into another as Video Input.
callback_urlstringOptional webhook URL for status updates
update_paramsobjectOptional parameters to override node parameters in the agent workflow
ignore_nodesstring[]Optional list of agent_node.id values to bypass for this run. Mosaic removes each ignored node from the runtime graph and rewires incoming edges directly to its downstream nodes.

​
Video URL Requirements & Limits

The video_urls field supports two types of URLs: YouTube URLs:
  • Supports standard YouTube video URLs (e.g., https://www.youtube.com/watch?v=VIDEO_ID)
  • Maximum duration: 1 hour per video
  • The system automatically validates the video exists and checks duration before processing
Signed URLs (HTTP/HTTPS):
  • Must be HTTP or HTTPS URLs pointing to video files
  • Maximum file size: 5 GB per video
  • Maximum duration: 3 hours per video

​
Modifying Node Parameters

You can override specific parameters for any node in your agent workflow using the update_params field. This allows you to dynamically change behavior (like clip duration, prompt text, or number of clips) at runtime. To find the correct parameters:
  1. Open your agent in the Mosaic Dashboard
  2. Click the settings menu on the node you want to modify
  3. Scroll down to the API info dropdown
  4. Open the dropdown to find the Agent node ID
  5. Click Copy params to get the JSON structure
The copied JSON will look like this, where the key is the Node ID (UUID) and the value object contains the parameters you can override: 
{
  "bf750792-a2e9-48c2-9d39-24f892772f6a": {
    "num_clips": 10,
    "target_duration": 60
  }
}
Pass this entire object as the update_params value in your API request.

​
Bypassing Nodes at Runtime

Use ignore_nodes to skip one or more nodes for a single run without editing the saved agent template. For each ignored node:
  • Incoming connections to the node are rewired to its downstream nodes
  • The ignored node is removed from the runtime DAG for that run only
  • The template itself is unchanged
{
  "video_urls": ["https://youtube.com/watch?v=..."],
  "ignore_nodes": [
    "8cbfd03e-6e85-4f3d-b4b9-8de0b5bfb6a4"
  ],
  "update_params": {
    "35a12345-6789-abcd-ef01-234567890abc": {
      "audio_id": "your-uploaded-audio-uuid"
    }
  }
}

​
Uploading Media for Node Parameters

Some nodes accept images, audio, or videos as parameters. To set these programmatically, use the Uploads API to upload your files and get their UUIDs: 
{
  "video_urls": ["https://youtube.com/watch?v=..."],
  "update_params": {
    "35a12345-6789-abcd-ef01-234567890abc": {
      "audio_id": "your-uploaded-audio-uuid"
    },
    "76b23456-7890-efab-cd12-345678901bcd": {
      "image_id": "your-uploaded-image-uuid"
    }
  }
}
See the Upload Flow for the complete upload process.

​
Chaining Runs with node_render_ids

You can feed outputs from a previous run directly into another agent by passing render IDs returned in webhooks or from GET /agent_run/[run_id] (outputs[].id). 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "node_render_ids": [
      "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "8cbfd03e-6e85-4f3d-b4b9-8de0b5bfb6a4"
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'

​
Response

{
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d"
}
The run_id is used to track the progress of your agent run.