Async jobs

For long-running captures or when you don't want to wait for the response, use async jobs. The API immediately returns a job ID, and you can poll for status or receive a webhook when complete.

Create async job

POST /v1/screenshots/async

Request body

Same parameters as the screenshots endpoint, plus:

Parameter	Type	Description
`webhookUrl`	string	URL to receive completion notification
`webhookSecret`	string	Secret for webhook signature verification
`outputs`	array	Multi-output extraction. Request multiple formats from one page load.

Example request

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/async' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "fullPage": true,
    "webhookUrl": "https://your-server.com/webhooks/screenshot"
  }'

Response

{
  "jobId": "job_abc123xyz",
  "status": "pending",
  "createdAt": "2025-01-15T10:30:00Z"
}

Get job status

GET /v1/screenshots/jobs/{jobId}

Example request

curl 'https://api.allscreenshots.com/v1/screenshots/jobs/job_abc123xyz' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response (pending)

{
  "jobId": "job_abc123xyz",
  "status": "pending",
  "createdAt": "2025-01-15T10:30:00Z"
}

Response (completed)

{
  "jobId": "job_abc123xyz",
  "status": "completed",
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:05Z",
  "result": {
    "url": "https://storage.allscreenshots.com/screenshots/abc123.png",
    "expiresAt": "2025-01-30T10:30:05Z",
    "size": 245678,
    "width": 1920,
    "height": 4500,
    "format": "png",
    "renderTime": 4250
  }
}

Response (failed)

{
  "jobId": "job_abc123xyz",
  "status": "failed",
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:31:00Z",
  "error": {
    "code": "timeout",
    "message": "Page load timed out after 60 seconds"
  }
}

Response (completed with multi-output)

When the job was created with an outputs array, the completed response includes per-output details:

{
  "jobId": "job_abc123xyz",
  "status": "completed",
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:05Z",
  "result": {
    "url": "https://storage.allscreenshots.com/screenshots/abc123.png",
    "expiresAt": "2025-01-30T10:30:05Z",
    "size": 245678,
    "width": 1920,
    "height": 4500,
    "format": "png",
    "renderTime": 4250
  },
  "outputs": {
    "screenshot": {
      "type": "screenshot",
      "contentType": "image/png",
      "size": 245678,
      "resultUrl": "https://api.allscreenshots.com/v1/screenshots/jobs/job_abc123xyz/result/screenshot",
      "storageUrl": "https://storage.allscreenshots.com/abc123/screenshot.png"
    },
    "markdown": {
      "type": "markdown",
      "contentType": "text/markdown",
      "size": 1200,
      "resultUrl": "https://api.allscreenshots.com/v1/screenshots/jobs/job_abc123xyz/result/markdown",
      "storageUrl": "https://storage.allscreenshots.com/abc123/content.md"
    }
  }
}

Get job result

Download the screenshot once the job is complete:

GET /v1/screenshots/jobs/{jobId}/result

The response format depends on the responseType that was set when the job was created:

binary or url (default): returns the raw image binary with the appropriate content type header.
base64: returns JSON with the image data encoded as a base64 string.

Binary result (default)

curl 'https://api.allscreenshots.com/v1/screenshots/jobs/job_abc123xyz/result' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output screenshot.png

Base64 result

If the job was created with responseType: "base64", the result endpoint returns JSON:

{
  "url": "https://example.com",
  "format": "png",
  "contentType": "image/png",
  "width": 1920,
  "height": 1080,
  "size": 245678,
  "renderTimeMs": 4250,
  "encoding": "base64",
  "data": "iVBORw0KGgo..."
}

Get specific output result

For multi-output jobs, download a specific output by its ID:

GET /v1/screenshots/jobs/{jobId}/result/{outputId}

As with the main result endpoint, the response format depends on the responseType of the original job. With responseType: "base64", the response is JSON with base64-encoded data instead of raw binary.

# Get the markdown output
curl 'https://api.allscreenshots.com/v1/screenshots/jobs/job_abc123xyz/result/markdown' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Get the screenshot output
curl 'https://api.allscreenshots.com/v1/screenshots/jobs/job_abc123xyz/result/screenshot' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output screenshot.png

Job results are available for 24 hours after completion. Download or store them before expiration.

Job statuses

Status	Description
`pending`	Job is queued for processing
`processing`	Screenshot capture in progress
`completed`	Capture successful, result available
`failed`	Capture failed, error details available

Polling vs webhooks

Polling

Simple to implement but less efficient:

async function waitForJob(jobId) {
  while (true) {
    const response = await fetch(
      `https://api.allscreenshots.com/v1/screenshots/jobs/${jobId}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );
    const job = await response.json();

    if (job.status === 'completed') {
      return job.result;
    }
    if (job.status === 'failed') {
      throw new Error(job.error.message);
    }

    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

Webhooks (recommended)

More efficient—no polling required:

// Create job with webhook
const response = await fetch('https://api.allscreenshots.com/v1/screenshots/async', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    webhookUrl: 'https://your-server.com/webhooks/screenshot',
    webhookSecret: 'your-webhook-secret',
  }),
});

// Handle webhook in your server
app.post('/webhooks/screenshot', (req, res) => {
  // Verify signature (see Webhooks docs)
  const job = req.body;

  if (job.status === 'completed') {
    console.log('Screenshot ready:', job.result.url);
  }

  res.sendStatus(200);
});

See Webhooks for complete webhook documentation.

Use cases

Async jobs are ideal for:

Full page captures: Pages that take longer to render
Batch processing: When combined with bulk jobs
Background tasks: When you don't need immediate results
Long timeouts: Pages with heavy JavaScript or slow loading assets

Example workflow

// 1. Create async job
const { jobId } = await createAsyncJob({
  url: 'https://example.com/report',
  fullPage: true,
  waitUntil: 'networkidle',
});

// 2. Store job ID in your database
await db.screenshots.create({
  jobId,
  url: 'https://example.com/report',
  status: 'processing',
});

// 3. Process webhook when complete
app.post('/webhooks/screenshot', async (req, res) => {
  const { jobId, status, result, error } = req.body;

  await db.screenshots.update(jobId, {
    status,
    screenshotUrl: result?.url,
    error: error?.message,
  });

  res.sendStatus(200);
});

Async jobs

On this page