Skip to content
Masko logomasko
Docs
QuickstartAPI reference
Documentation

Jobs & Polling

Use Masko-API-Version: 2026-09-26 on shared job endpoints to receive mascot_id. The equivalent api_version=2026-09-26 query selector is included in canonical polling links. Unversioned requests remain legacy-compatible. Historical generation_context, input_data and output_data are immutable receipts: their stored keys and hashes are not rewritten.

Every generation creates a job. Track progress and get results by polling the job endpoint, or use long-polling to wait for completion without repeated requests.

Job Lifecycle

Every job moves through a simple lifecycle: pending - processing - completed or failed. A job enters pending when the generation request is accepted, transitions to processing once a worker picks it up, and resolves to either completed with asset URLs or failed with an error message.

pending  -->  processing  -->  completed
                           \-->  failed

List Jobs

Retrieve all your jobs with optional filters. Use query parameters to narrow results by status, mascot, or type.

# 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"

Available filters: ?status=pending|processing|completed|failed, ?mascot_id=..., ?type=item_generation|image_generation|logo|animation|reverse|size_variant|size_variant_batch|export_animation|scene_generation.

Get Job Detail

Fetch a single job by ID. Completed jobs include full output data with asset IDs and CDN URLs.

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"
#     }
#   }
# }

Long-Polling

Instead of polling repeatedly, use long-polling. Add ?wait=true and the server holds the connection open until the job completes or the timeout is reached. The default timeout is 120 seconds, configurable with ?timeout=.

# 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 vs Webhooks

  • Long-polling - simplest approach. Best for scripts, CLI tools, and prototyping. One request, one response, no infrastructure needed.
  • Webhooks - best for production. Your server gets notified when jobs complete. No open connections, handles high volumes, works behind load balancers.
  • Hybrid - use webhooks for background processing and long-polling for user-facing flows where you need immediate feedback.

Webhooks

Get notified when jobs complete instead of polling. Set up webhook endpoints for production use.

List & Browse

Browse your projects, mascots, and assets to find the resources you need.

Media readiness

A parent generation job and its derived formats can finish at different times. Check the required asset type and size_variants before playing it. For a canvas, use status.media.preview.ready; for a developer run, wait for its runtime readiness and version reference. A returned CDN URL may still serve a placeholder.

Trace the variant used

GET /v1/jobs/{id} returns variant_id and, when recorded by the generation path, generation_context. The latter is the frozen context used for that job: the variant ID and name, engine hash, your mascot prompt and style, resolved reference asset IDs and individual asset inputs. It is not reconstructed from the mascot's currently active variant. Internal execution details are never included in public job responses. Your mascot description, style, references and requested edits remain available. Original-context, cross-variant transitions and older untagged jobs report a null variant_id; inspect the transition endpoints to distinguish them.

Use GET /v1/jobs?mascot_id=MASCOT_UUID&variant_id=VARIANT_UUID to list work generated for a specific variant. Generated assets retain their job_id, so their generation context can be traced through that job.

For transitions, generation_context.transition.before and .after each record asset_id, collection_id, variant_id, variant_name, context_source and the saved customer-authored generation context. Internal execution receipts remain private. A reverse job swaps the endpoint roles; it has no new writer receipt because it reverses an existing clip.

Filter transitions by role with from_variant_id or to_variant_id:

GET /v1/jobs?mascot_id=MASCOT_UUID&to_variant_id=VARIANT_UUID

These filters accept named variant UUIDs. To find Original endpoints, inspect null endpoint IDs in the mascot's jobs. Historical jobs without a recorded transition are not retroactively assigned one.

Video editing creates a video_edit job. For a transition edit, the job retains generation_context.transition.before and .after and adds generation_context.transition_edit: the source video ID and requested edit. Internal templates and compiled instructions are not returned. Repeated edits retain the same endpoint identities; reversing the resulting video swaps them normally.

Create cursor followers with POST /v1/mascots/{id}/interactive using source_asset_id and kind: "cursor-follower". The completed source image must have transparency; the source variant is retained automatically. It costs 9 credits and returns 202 with data.job_id, data.asset_id, data.variant_id, and data.poll_url. These are interactive_generation jobs; assets use interactive for the set and interactive_frame for each direction. Send once and poll; a repeated POST creates a new charged set. Use GET /v1/mascots/{id}/cdn-export after completion and hosting to retrieve its manifest and all nine CDN WebP URLs. The web app provides the component ZIP. Generic job URLs are not a direction map.