Skip to main content
GET
/
agent_run
/
{run_id}
Get Agent Run
curl --request GET \
  --url https://api.example.com/agent_run/{run_id}
Poll this endpoint to check the status of your agent run and retrieve outputs.

​
Request

curl -X GET "https://api.mosaic.so/agent_run/[run_id]" \
  -H "Authorization: Bearer mk_your_api_key"

​
Response

{
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "started_at": "2025-01-10T14:30:00Z",
  "status": "completed",
  "status_message": null,
  "needs_credits": false,
  "errors": [],
  "node_status_counts": {
    "completed": 10,
    "in_progress": 0,
    "failed": 0
  },
  "inputs": [
    {
      "video_url": "https://storage.googleapis.com/mosaic-inputs/...",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-inputs/..."
    }
  ],
  "outputs": [
    {
      "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "video_url": "https://storage.googleapis.com/mosaic-outputs/...",
      "thumbnail_url": "https://storage.googleapis.com/mosaic-thumbnails/...",
      "premiere_prproj_url": "https://storage.googleapis.com/mosaic-outputs/.../timeline.zip?...",
      "completed_at": "2025-01-10T14:35:30Z",
      "original_node_id": "2ba7b810-9dad-11d1-80b4-00c04fd430c8"
    }
  ]
}

​
Output Fields

FieldTypeDescription
idstringUnique identifier for this output render
video_urlstringSigned URL to download the rendered video (valid for 7 days)
thumbnail_urlstring | nullSigned URL to download the video thumbnail
premiere_prproj_urlstring | nullSigned URL to download the Premiere Pro timeline zip attached to this render (when available)
completed_atstringISO 8601 timestamp when this output finished rendering
original_node_idstring | nullTemplate agent_node_id this output originated from. Use this to map outputs to specific nodes in your agent.
Tracking outputs: Use original_node_id to identify which node in your agent template produced each output. This allows you to consistently map outputs to your application logic across multiple runs.

​
Run Fields

FieldTypeDescription
agent_idstringAgent UUID that started this run.
statusstringOverall run status (see Status Values below).
status_messagestring | nullHuman-readable detail about the run status.
needs_creditsbooleantrue when one or more runtime tasks in this run are marked needs_credits=true (insufficient credits).
errorsarrayError messages grouped by template node. Each entry has original_node_id and messages[]. Empty array [] when the run has no errors.
node_status_countsobjectCounts of nodes in completed, in_progress, and failed states.
For node-level statuses, error details, and credit-blocked details, use Get Agent Run Nodes.
If needs_credits is true, first check GET /plan. If no paid plan is active, choose one via GET /plan/list and POST /plan/upgrade (complete checkout when requires_checkout: true). You can then enable auto top-ups with POST /credits/settings if your active plan is creator, creator_annual, professional, or professional_annual, and finally call Resume Agent Run to re-queue failed/blocked runtime nodes in the same run.

​
Status Values

StatusDescription
runningAgent is processing your videos
completedProcessing finished successfully
partial_completeSome outputs finished successfully, but others failed
failedThe entire run failed, no outputs generated
cancelledThe run was cancelled by the user