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	`false`	Block ads
`blockCookieBanners`	boolean	`false`	Block cookie banners
`blockLevel`	string	`"none"`	Domain blocking level

webhookUrl / webhookSecret

Optional webhook configuration for completion notification.

Response

{
  "bulkJobId": "bulk_abc123xyz",
  "status": "pending",
  "totalUrls": 3,
  "createdAt": "2025-01-15T10:30:00Z"
}

Get bulk job status

GET /v1/screenshots/bulk/{bulkJobId}

Response (in progress)

{
  "bulkJobId": "bulk_abc123xyz",
  "status": "processing",
  "totalUrls": 3,
  "completedUrls": 1,
  "failedUrls": 0,
  "createdAt": "2025-01-15T10:30:00Z",
  "jobs": [
    {
      "jobId": "job_001",
      "url": "https://example1.com",
      "status": "completed"
    },
    {
      "jobId": "job_002",
      "url": "https://example2.com",
      "status": "processing"
    },
    {
      "jobId": "job_003",
      "url": "https://example3.com",
      "status": "pending"
    }
  ]
}

Response (completed)

{
  "bulkJobId": "bulk_abc123xyz",
  "status": "completed",
  "totalUrls": 3,
  "completedUrls": 3,
  "failedUrls": 0,
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:45Z",
  "jobs": [
    {
      "jobId": "job_001",
      "url": "https://example1.com",
      "status": "completed",
      "result": {
        "url": "https://storage.allscreenshots.com/abc.png",
        "size": 123456,
        "width": 1280,
        "height": 720
      }
    },
    {
      "jobId": "job_002",
      "url": "https://example2.com",
      "status": "completed",
      "result": {
        "url": "https://storage.allscreenshots.com/def.png",
        "size": 234567,
        "width": 1280,
        "height": 720
      }
    },
    {
      "jobId": "job_003",
      "url": "https://example3.com",
      "status": "completed",
      "result": {
        "url": "https://storage.allscreenshots.com/ghi.png",
        "size": 345678,
        "width": 1280,
        "height": 3200
      }
    }
  ]
}

Examples

Capture competitor homepages

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/bulk' \
  -H 'Authorization: Bearer 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 'Authorization: Bearer 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 'Authorization: Bearer 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"
    }
  }'

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, status, jobs } = req.body;

  if (status === 'completed') {
    for (const job of jobs) {
      if (job.status === 'completed') {
        await saveScreenshot(job.url, job.result.url);
      }
    }
  }

  res.sendStatus(200);
});

Limits

Limit	Value
Maximum URLs per bulk job	100
Maximum concurrent bulk jobs	5
Job result retention	24 hours

Bulk screenshots

On this page