Jobs & Polling

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, collection, or type.

# List all jobs
curl https://api.masko.ai/v1/jobs \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Filter by status and collection
curl "https://api.masko.ai/v1/jobs?status=completed&collection_id=COLLECTION_ID" \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Filter by type
curl "https://api.masko.ai/v1/jobs?type=animation" \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Available filters: ?status=pending|processing|completed|failed, ?collection_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"

# Completed job response:
# {
#   "data": {
#     "id": "job_abc123",
#     "status": "completed",
#     "type": "item_generation",
#     "collection_id": "col_xyz",
#     "cost_credits": 21,
#     "created_at": "2026-03-28T10:00:00Z",
#     "updated_at": "2026-03-28T10:01:32Z",
#     "item_id": "item_456",
#     "item_name": "Wave",
#     "urls": {
#       "image": "https://assets.masko.ai/col_xyz/image.png",
#       "webm": "https://assets.masko.ai/col_xyz/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"

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