Jobs and polling
Every generation creates a job. Poll it, long-poll until it finishes, or get notified with webhooks.
generation_context, input_data and output_data are receipts saved when the job ran, and keep their original field names. The context the job ran with is the top-level generation_context; input_data holds the other inputs.
Job lifecycle
A job is pending when accepted and processing once a worker picks it up, then ends completed with asset URLs or failed with an error.
pending --> processing --> completed
\--> failedList jobs
# List all jobs
curl https://api.masko.ai/v1/jobs \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Masko-API-Version: 2026-09-26"
# Filter by status and mascot
curl "https://api.masko.ai/v1/jobs?status=completed&mascot_id=MASCOT_ID" \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Masko-API-Version: 2026-09-26"
# Filter by type
curl "https://api.masko.ai/v1/jobs?type=animation" \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Masko-API-Version: 2026-09-26"Filters: status (pending, processing, completed or failed; any other value answers 400), mascot_id, and type (item_generation, image_generation, logo, animation, reverse, size_variant, size_variant_batch, export_animation, background_generation). Variant filters are in trace the variant used.
Add top_level=true to leave out jobs that another job started: the clips of a canvas generation and the files of a batch export. Standalone exports stay. Each row also has parent_job_id (the job that started it, or null), canvas_id, item_name (the pose or animation it made, or null), and credits_refunded when credits came back.
Get job detail
Completed jobs list their files in urls: the CDN link of each hosted file, and a signed link that expires within hours for the others. Under the same key as each link, file_sizes gives the file's size in bytes (null when the file cannot be read) and asset_ids gives its asset ID, to use with the asset endpoints such as media exports. A key is the file type, such as webm, or the type and width for a size variant, such as webm_360. A talking animation also lists its stacked_video and stacked_video_av1 files. A logo lists its master as image, its transparent copy as transparent_image, and each export under its own name, such as png_1024, ios_180 or favicon_ico.
A failed job gives error, a message to show, and error_code, a stable category: copyright_blocked, safety_blocked and image_empty need a different request or picture, while provider_busy, provider_unavailable, timeout, animation_failed, source_unavailable, authentication_error and unknown are failures on Masko's side, not in the request, so trying the same request again usually works. A failed job can still list files it finished, such as the picture of an animation whose video failed. A failed animation of an existing pose lists no picture: the pose is its input, not its work.
credits_refunded gives the credits that came back for work the job did not deliver; cost_credits stays what was charged. It is absent when nothing was refunded.
A canvas_orchestration job completes even when clips fail. Its progress gives total, failed and dispatched clip counts once the run ends (null before), and release tells whether the canvas was released, when the run was asked to release it.
curl https://api.masko.ai/v1/jobs/JOB_ID \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Masko-API-Version: 2026-09-26"
# Completed job response:
# {
# "data": {
# "id": "0818df65-d092-5901-a506-3b2e64fb88ef",
# "status": "completed",
# "type": "item_generation",
# "mascot_id": "c244e7b1-5655-5540-89a8-516b09bd4985",
# "cost_credits": 21,
# "created_at": "2026-03-28T10:00:00Z",
# "updated_at": "2026-03-28T10:01:32Z",
# "item_id": "e1a868c7-82b1-5d17-947b-ab4eeebd6fc3",
# "item_name": "Wave",
# "urls": {
# "image": "https://assets.masko.ai/c244e7b1-5655-5540-89a8-516b09bd4985/image.png",
# "webm": "https://assets.masko.ai/c244e7b1-5655-5540-89a8-516b09bd4985/video.webm"
# },
# "file_sizes": {
# "image": 412833,
# "webm": 1370412
# },
# "asset_ids": {
# "image": "3c8ce568-35ce-59c2-b3f8-9fb7e4a16e52",
# "webm": "3db2d3be-a85a-5e9e-85fc-02100b19d8cb"
# }
# }
# }
# Failed job response:
# {
# "data": {
# "id": "5b1f0c2e-7d4a-4f8b-9c3e-2a6d8e1f4b70",
# "status": "failed",
# "type": "item_generation",
# "mascot_id": "c244e7b1-5655-5540-89a8-516b09bd4985",
# "cost_credits": 12,
# "error": "AI service is temporarily unavailable. Please try again in a few minutes. Your credits were refunded.",
# "error_code": "provider_unavailable",
# "credits_refunded": 12
# }
# }Long polling
Add ?wait=true to hold the request open until the job finishes or timeout (default 120 seconds) passes. A timeout returns the current status and does not cancel the job.
# Wait up to 120 seconds for the job to complete
curl "https://api.masko.ai/v1/jobs/JOB_ID?wait=true&timeout=120" \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Masko-API-Version: 2026-09-26"
# Returns immediately if already completed.
# Returns the job object when it completes.
# Returns with current status if timeout is reached.When to poll and when to use webhooks
- Long-polling: simplest, for scripts, CLI tools and prototypes.
- Webhooks: for production. Your server is notified, with no open connections.
- Both: webhooks for background work, long-polling where a user waits for the result.
Media readiness
A job and its derived formats can finish at different times, and a returned CDN URL may still serve a placeholder. Check the required asset type and size_variants before playback. For a canvas use status.media.preview.ready; for a developer run, wait for its runtime readiness and version reference.
Trace the variant used
GET /v1/jobs/{id} returns variant_id and, when recorded, generation_context: the frozen context the job used (variant ID and name, engine hash, mascot prompt and style, resolved reference asset IDs and asset inputs). It never reflects the currently active variant, and internal execution details are never returned. Original-context jobs, cross-variant transitions and older untagged jobs have a null variant_id.
GET /v1/jobs?mascot_id=MASCOT_UUID&variant_id=VARIANT_UUIDlists work for one variant. Generated assets keep theirjob_id, so you can trace them back.from_variant_idandto_variant_idfilter transitions by role and accept named variant UUIDs. Original endpoints have null IDs, so find them by inspecting the mascot's jobs.
GET /v1/jobs?mascot_id=MASCOT_UUID&to_variant_id=VARIANT_UUIDFor transitions, generation_context.transition.before and .after each record asset_id, collection_id, variant_id, variant_name, context_source and the saved generation context. A reverse job swaps the roles without a new writer receipt. Older jobs without a recorded transition are not backfilled.
A video edit creates a video_edit job. For a transition edit, it keeps transition.before and .after and adds generation_context.transition_edit with the source video ID and requested edit. Repeated edits keep the endpoint identities.
Cursor followers create interactive_generation jobs; get their nine image URLs from GET /v1/mascots/{id}/cdn-export.
