Bulk screenshots

Capture up to 100 URLs in a single API call. Bulk jobs run asynchronously and notify you via webhook when all captures are complete.

For larger lists or resumable uploads, use Screenshot batches. Existing bulk jobs also appear in the dashboard’s Batches view.

Create bulk job

POST /v1/screenshots/bulk

Request body

{
  "urls": [
    { "url": "https://example1.com" },
    { "url": "https://example2.com" },
    { "url": "https://example3.com", "options": { "fullPage": true } }
  ],
  "defaults": {
    "format": "png",
    "viewport": { "width": 1280, "height": 720 },
    "blockAds": true
  },
  "webhookUrl": "https://your-server.com/webhooks/bulk",
  "webhookSecret": "your-secret"
}

Parameters

urls (required)

Array of URL objects (1-100 items):

Field	Type	Description
`url`	string	URL to capture (required)
`options`	object	Per-URL option overrides

defaults

Default options applied to all URLs unless overridden:

Field	Type	Default	Description
`viewport`	object	`{width: 1920, height: 1080}`	Viewport configuration
`device`	string	-	Device preset
`format`	string	`"webp"`	Output format
`fullPage`	boolean	`false`	Capture full page
`quality`	integer	`80`	Image quality (1-100)
`delay`	integer	`0`	Delay before capture (ms)
`waitFor`	string	-	CSS selector to wait for
`waitUntil`	string	`"load"`	Page load event
`timeout`	integer	`30000`	Max wait time (ms)
`darkMode`	boolean	`false`	Dark mode emulation
`customCss`	string	-	Custom CSS to inject
`blockAds`	boolean	`true`	Block ads. Set to `false` to disable.
`blockCookieBanners`	boolean	`true`	Block cookie banners. Set to `false` to disable.
`blockPopups`	boolean	`true`	Block marketing and location overlays. Set to `false` to preserve them.
`blockLevel`	string	`"none"`	Domain blocking level
`actions`	array	-	Interactive actions run before each capture (max 25)
`outputs`	array	-	Multi-output extraction applied to all URLs

Per-URL options accept the same actions field and override the defaults for that URL.

webhookUrl / webhookSecret

Optional webhook configuration for completion notification.

Response

{
  "id": "bulkabc123",
  "status": "PROCESSING",
  "totalJobs": 3,
  "completedJobs": 0,
  "failedJobs": 0,
  "progress": 0,
  "jobs": [
    { "id": "job001abc", "url": "https://example1.com", "status": "QUEUED" },
    { "id": "job002abc", "url": "https://example2.com", "status": "QUEUED" },
    { "id": "job003abc", "url": "https://example3.com", "status": "QUEUED" }
  ],
  "createdAt": "2025-01-15T10:30:00Z"
}

Get bulk job status

GET /v1/screenshots/bulk/{bulkJobId}

Response (in progress)

{
  "id": "bulkabc123",
  "status": "PROCESSING",
  "totalJobs": 3,
  "completedJobs": 1,
  "failedJobs": 0,
  "progress": 33,
  "createdAt": "2025-01-15T10:30:00Z",
  "jobs": [
    {
      "id": "job001abc",
      "url": "https://example1.com",
      "status": "COMPLETED",
      "resultUrl": "https://api.allscreenshots.com/v1/screenshots/jobs/job001abc/result",
      "storageUrl": "https://storage.allscreenshots.com/job001abc.png",
      "format": "PNG",
      "width": 1280,
      "height": 720,
      "fileSize": 123456,
      "renderTimeMs": 1200,
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:30:05Z"
    },
    {
      "id": "job002abc",
      "url": "https://example2.com",
      "status": "PROCESSING",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "job003abc",
      "url": "https://example3.com",
      "status": "QUEUED",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Response (completed)

{
  "id": "bulkabc123",
  "status": "COMPLETED",
  "totalJobs": 3,
  "completedJobs": 3,
  "failedJobs": 0,
  "progress": 100,
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:45Z",
  "jobs": [
    {
      "id": "job001abc",
      "url": "https://example1.com",
      "status": "COMPLETED",
      "resultUrl": "https://api.allscreenshots.com/v1/screenshots/jobs/job001abc/result",
      "storageUrl": "https://storage.allscreenshots.com/job001abc.png",
      "format": "PNG",
      "width": 1280,
      "height": 720,
      "fileSize": 123456,
      "renderTimeMs": 1200,
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:30:05Z"
    },
    {
      "id": "job002abc",
      "url": "https://example2.com",
      "status": "COMPLETED",
      "resultUrl": "https://api.allscreenshots.com/v1/screenshots/jobs/job002abc/result",
      "storageUrl": "https://storage.allscreenshots.com/job002abc.png",
      "format": "PNG",
      "width": 1280,
      "height": 720,
      "fileSize": 234567,
      "renderTimeMs": 1400,
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:30:20Z"
    },
    {
      "id": "job003abc",
      "url": "https://example3.com",
      "status": "COMPLETED",
      "resultUrl": "https://api.allscreenshots.com/v1/screenshots/jobs/job003abc/result",
      "storageUrl": "https://storage.allscreenshots.com/job003abc.png",
      "format": "PNG",
      "width": 1280,
      "height": 3200,
      "fileSize": 345678,
      "renderTimeMs": 2400,
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:30:45Z"
    }
  ]
}

Examples

Capture competitor homepages

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/bulk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      { "url": "https://competitor1.com" },
      { "url": "https://competitor2.com" },
      { "url": "https://competitor3.com" }
    ],
    "defaults": {
      "viewport": { "width": 1920, "height": 1080 },
      "blockAds": true,
      "blockCookieBanners": true,
      "blockPopups": true
    },
    "webhookUrl": "https://your-server.com/webhooks/competitors"
  }'

Multiple devices for one URL

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/bulk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      { "url": "https://yoursite.com", "options": { "device": "desktop_hd" } },
      { "url": "https://yoursite.com", "options": { "device": "iphone_15" } },
      { "url": "https://yoursite.com", "options": { "device": "ipad_pro_11" } }
    ],
    "defaults": {
      "format": "png",
      "blockAds": true
    }
  }'

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/bulk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      { "url": "https://blog.example.com/post-1" },
      { "url": "https://blog.example.com/post-2" },
      { "url": "https://blog.example.com/post-3" }
    ],
    "defaults": {
      "device": "twitter_card",
      "waitUntil": "networkidle"
    }
  }'

Bulk with multi-output

Capture screenshots and markdown for multiple URLs:

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/bulk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      { "url": "https://blog.example.com/post-1" },
      { "url": "https://blog.example.com/post-2" },
      { "url": "https://blog.example.com/post-3" }
    ],
    "defaults": {
      "outputs": [
        { "type": "screenshot", "format": "png" },
        { "type": "markdown", "mainContentOnly": true }
      ]
    },
    "webhookUrl": "https://your-server.com/webhooks/bulk"
  }'

Best practices

Bulk jobs are more efficient than individual requests. Use them whenever you need to capture more than 2-3 URLs.

Group similar captures

Put URLs with similar options in the same bulk job to simplify defaults:

{
  "urls": [
    { "url": "https://site1.com" },
    { "url": "https://site2.com" },
    { "url": "https://site3.com" }
  ],
  "defaults": {
    "device": "iphone_15",
    "fullPage": true
  }
}

Handle partial failures

Some URLs may fail while others succeed. Check individual job statuses:

const bulkJob = await getBulkJob(bulkJobId);

const successful = bulkJob.jobs.filter(j => j.status === 'COMPLETED');
const failed = bulkJob.jobs.filter(j => j.status === 'FAILED');

console.log(`${successful.length} succeeded, ${failed.length} failed`);

// Retry failed URLs if needed
if (failed.length > 0) {
  const retryUrls = failed.map(j => ({ url: j.url }));
  await createBulkJob({ urls: retryUrls });
}

Use webhooks for completion

Instead of polling, use webhooks to receive notifications:

app.post('/webhooks/bulk', async (req, res) => {
  const { bulkJobId, jobs } = req.body.data;

  if (jobs.length > 0) {
    for (const job of jobs) {
      if (job.status === 'COMPLETED') {
        await saveScreenshot(job.url, job.resultUrl);
      }
    }
  }

  res.sendStatus(200);
});

Limits

Limit	Value
Maximum URLs per bulk job	100
Maximum concurrent bulk jobs	5
Job result retention	7 days by default

Bulk screenshots

On this page