Async Jobs

Batch screenshots and sitemap crawls run as background jobs. Use the Jobs API to poll for status and download results when complete.

Job lifecycle

pending → processing → completed
                     ↘ partial   (some URLs failed)
                     ↘ failed    (all URLs failed)

List jobs

GET/v1/jobs

curl "https://api.snapsharp.dev/v1/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer sk_live_..."

Query parameters

Parameter	Type	Default	Description
`status`	`string`	—	Filter by status: `pending`, `processing`, `completed`, `failed`, `partial`
`limit`	`integer`	`20`	Max results (up to 100)
`offset`	`integer`	`0`	Pagination offset

Get job status

GET/v1/jobs/{id}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "batch",
  "status": "completed",
  "progress": {
    "total": 10,
    "completed": 9,
    "failed": 1,
    "percentage": 100
  },
  "result_url": "/v1/jobs/3fa85f64.../download",
  "download_url": "/v1/jobs/3fa85f64.../download",
  "created_at": "2026-04-01T10:00:00Z",
  "started_at": "2026-04-01T10:00:05Z",
  "completed_at": "2026-04-01T10:02:30Z",
  "expires_at": "2026-04-02T10:02:30Z"
}

Download result

GET/v1/jobs/{id}/download

Returns a ZIP archive. Available only when status is "completed" or "partial".

curl "https://api.snapsharp.dev/v1/jobs/JOB_ID/download" \
  -H "Authorization: Bearer sk_live_..." \
  -o result.zip

Results expire 24 hours after job completion. The download returns HTTP 410 (Gone) after expiry.

Webhook callbacks

Pass a callback_url when creating a batch or sitemap job to receive a webhook notification on completion:

{
  "job_id": "3fa85f64...",
  "type": "batch",
  "status": "completed",
  "progress": { "total": 10, "completed": 10, "failed": 0 },
  "result_url": "/v1/jobs/3fa85f64.../download"
}

Polling example (Node.js)

async function waitForJob(client, jobId, intervalMs = 2000) {
  while (true) {
    const job = await client.getJob(jobId);
    
    if (['completed', 'partial', 'failed'].includes(job.status)) {
      return job;
    }
    
    await new Promise((r) => setTimeout(r, intervalMs));
  }
}

const job = await client.batch(['https://example.com'], { format: 'png' });
const result = await waitForJob(client, job.job_id);

if (result.status !== 'failed') {
  const zip = await client.downloadJob(job.job_id);
  // Save zip...
}