Skip to main content
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:
FieldTypeDescription
flagstring"RUN_STARTED", "RUN_PROGRESS", or "RUN_FINISHED"
agent_idstringAgent UUID
run_idstringRun UUID
statusstringCurrent run status
node_status_countsobject{ completed, in_progress, failed }
triggered_byobject | nullWhat 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
}
Additional fields: 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
}
Additional fields:
FieldTypeDescription
updated_nodes[].original_node_idstring | nullTemplate agent_node_id — use to map back to your agent
updated_nodes[].statusstringcompleted, running, queued, failed, blocked, partial_complete
updated_nodes[].status_messagestring | nullHuman-readable message
updated_nodes[].errorsarrayError messages from failed tasks in this node. Empty array when the node has no errors.
updated_nodes[].outputsarrayOutputs 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
}
When a run fails, 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 },
  "..."
}
Additional fields:
FieldTypeDescription
statusstringcompleted, partial_complete, or failed
status_messagestring | nullHuman-readable detail on failure
needs_creditsbooleantrue when one or more runtime tasks in the run are marked needs_credits=true (insufficient credits).
errorsarrayError messages grouped by template node. Empty array [] when the run has no errors.
errors[].original_node_idstring | nullTemplate agent_node_id the errors originated from
errors[].messagesarrayList of error messages from failed tasks in this node
inputsarray{ video_url, thumbnail_url } for each input
outputsarrayFinal rendered outputs (see below)
When 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:
FieldTypeDescription
idstringRender ID — use for chaining runs via node_render_ids
video_urlstringSigned download URL (valid 7 days)
thumbnail_urlstring | nullSigned thumbnail URL
premiere_prproj_urlstring | nullSigned URL for the Premiere Pro timeline zip attached to this render (when available)
completed_atstringISO 8601 timestamp
original_node_idstring | nullTemplate 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

StatusMeaning
runningProcessing in progress
completedAll outputs generated successfully
partial_completeSome outputs succeeded, others failed
failedNo outputs generated
cancelledCancelled by user