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.
Provide a callback_url when calling Run Agent to receive webhook POSTs for run lifecycle events.
Authentication
If you have a webhook secret configured, every webhook includes an X-Mosaic-Signature header containing the secret as a plaintext string. Validate with a direct comparison:
if request.headers.get('X-Mosaic-Signature') != os.environ['MOSAIC_WEBHOOK_SECRET']:
return {"error": "Unauthorized"}, 401
Common Fields
Every webhook payload contains these fields:
| Field | Type | Description |
|---|
flag | string | "RUN_STARTED", "RUN_PROGRESS", or "RUN_FINISHED" |
agent_id | string | Agent UUID |
run_id | string | Run UUID |
status | string | Current run status |
node_status_counts | object | { completed, in_progress, failed } |
triggered_by | object | null | What initiated the run (see below) |
needs_credits and errors are included on RUN_FINISHED payloads when available.
RUN_STARTED
Sent when the run begins.
{
"flag": "RUN_STARTED",
"agent_id": "123e4567-e89b-12d3-a456-789012345678",
"run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
"status": "running",
"inputs": [
{
"video_url": "https://storage.googleapis.com/.../input.mp4",
"thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg"
}
],
"node_status_counts": { "completed": 1, "in_progress": 5, "failed": 0 },
"triggered_by": null
}
inputs — array of { video_url, thumbnail_url } for the input videos.
RUN_PROGRESS
Sent when one or more nodes change status. Useful for progress tracking without polling.
{
"flag": "RUN_PROGRESS",
"agent_id": "123e4567-e89b-12d3-a456-789012345678",
"run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
"status": "running",
"node_status_counts": { "completed": 4, "in_progress": 3, "failed": 0 },
"updated_nodes": [
{
"original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8",
"status": "completed",
"status_message": null,
"errors": [],
"outputs": [
{
"id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
"video_url": "https://storage.googleapis.com/...",
"thumbnail_url": "https://storage.googleapis.com/...",
"premiere_prproj_url": "https://storage.googleapis.com/.../timeline.zip?...",
"completed_at": "2024-01-15T10:35:00Z",
"original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
]
}
],
"triggered_by": null
}
| Field | Type | Description |
|---|
updated_nodes[].original_node_id | string | null | Template agent_node_id — use to map back to your agent |
updated_nodes[].status | string | completed, running, queued, failed, blocked, partial_complete |
updated_nodes[].status_message | string | null | Human-readable message |
updated_nodes[].errors | array | Error messages from failed tasks in this node. Empty array when the node has no errors. |
updated_nodes[].outputs | array | Outputs produced by this node (if any) |
RUN_FINISHED
Sent when the run reaches a terminal state. Contains all final outputs.
{
"flag": "RUN_FINISHED",
"agent_id": "123e4567-e89b-12d3-a456-789012345678",
"run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d",
"status": "completed",
"status_message": null,
"needs_credits": false,
"errors": [],
"inputs": [
{
"video_url": "https://storage.googleapis.com/.../input.mp4",
"thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg"
}
],
"outputs": [
{
"id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
"video_url": "https://storage.googleapis.com/.../output.mp4",
"thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg",
"premiere_prproj_url": "https://storage.googleapis.com/.../timeline.zip?...",
"completed_at": "2024-01-15T10:35:00Z",
"original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
],
"node_status_counts": { "completed": 10, "in_progress": 0, "failed": 0 },
"triggered_by": null
}
errors contains error details grouped by template node:
{
"flag": "RUN_FINISHED",
"status": "failed",
"status_message": "Processing failed for one or more tiles.",
"errors": [
{
"original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8",
"messages": ["FFmpeg render failed: output format not supported"]
},
{
"original_node_id": "3ca7b810-9dad-11d1-80b4-00c04fd430c8",
"messages": [
"Audio transcription timed out after 300s",
"Retry failed: service unavailable"
]
}
],
"node_status_counts": { "completed": 3, "in_progress": 0, "failed": 2 },
"..."
}
| Field | Type | Description |
|---|
status | string | completed, partial_complete, or failed |
status_message | string | null | Human-readable detail on failure |
needs_credits | boolean | true when one or more runtime tasks in the run are marked needs_credits=true (insufficient credits). |
errors | array | Error messages grouped by template node. Empty array [] when the run has no errors. |
errors[].original_node_id | string | null | Template agent_node_id the errors originated from |
errors[].messages | array | List of error messages from failed tasks in this node |
inputs | array | { video_url, thumbnail_url } for each input |
outputs | array | Final rendered outputs (see below) |
needs_credits is true, check GET /plan first. If no paid plan is active, list plans with GET /plan/list, upgrade with POST /plan/upgrade, and complete checkout if requires_checkout: true. After plan activation, optionally enable auto top-ups via POST /credits/settings if your active plan is creator, creator_annual, professional, or professional_annual, then call POST /agent_run/{run_id}/resume to continue the run.
Output fields:
| Field | Type | Description |
|---|
id | string | Render ID — use for chaining runs via node_render_ids |
video_url | string | Signed download URL (valid 7 days) |
thumbnail_url | string | null | Signed thumbnail URL |
premiere_prproj_url | string | null | Signed URL for the Premiere Pro timeline zip attached to this render (when available) |
completed_at | string | ISO 8601 timestamp |
original_node_id | string | null | Template node that produced this output |
triggered_by
Present when the run was started by a trigger or YouTube URL. null for standard API runs.
{
"type": "youtube",
"channel_id": "UCxxxxxxxxxxxxxx",
"video_id": "dQw4w9WgXcQ",
"video_title": "Never Gonna Give You Up",
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"triggered_at": "2024-01-15T10:30:00Z",
"trigger_id": "8f7d6c5b-4a3e-2b1f-9d8c-1a2b3c4d5e6f"
}
type is one of "youtube", "schedule", or "manual".
Run Status Values
| Status | Meaning |
|---|
running | Processing in progress |
completed | All outputs generated successfully |
partial_complete | Some outputs succeeded, others failed |
failed | No outputs generated |
cancelled | Cancelled by user |
