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.

GET/v1/jobs
# 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=image|animation|logo|edit.

Get Job Detail

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

GET/v1/jobs/:id
curl https://api.masko.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Completed job response:
# {
#   "id": "job_abc123",
#   "status": "completed",
#   "type": "animation",
#   "collection_id": "col_xyz",
#   "created_at": "2026-03-28T10:00:00Z",
#   "completed_at": "2026-03-28T10:01:32Z",
#   "output_data": {
#     "item_id": "item_456",
#     "duration": 4
#   },
#   "asset_ids": {
#     "image": "ast_img_001",
#     "transparent_image": "ast_timg_001",
#     "video": "ast_vid_001",
#     "webm": "ast_webm_001",
#     "hevc": "ast_hevc_001"
#   },
#   "urls": {
#     "image": "https://assets.masko.ai/col_xyz/image.png",
#     "transparent_image": "https://assets.masko.ai/col_xyz/transparent.png",
#     "video": "https://assets.masko.ai/col_xyz/video.mp4",
#     "webm": "https://assets.masko.ai/col_xyz/video.webm",
#     "hevc": "https://assets.masko.ai/col_xyz/video_hevc.mp4"
#   }
# }

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

GET/v1/jobs/:id?wait=true&timeout=120
# 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.

Webhooks

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

List & Browse

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