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.

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	`"png"`	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.
`blockLevel`	string	`"none"`	Domain blocking level
`outputs`	array	-	Multi-output extraction applied to all URLs

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
    },
    "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