Batch processing

Screenshotly’s batch capture feature lets you capture screenshots of multiple URLs in a single request, with shared settings applied to all URLs.

Basic batch request

const result = await client.captureBatch({
  urls: [
    'https://example.com',
    'https://google.com',
    'https://github.com'
  ],
  options: {
    format: 'png',
    viewport_width: 1280,
    viewport_height: 800,
    full_page: true
  }
});

if (result.success) {
  console.log(`Succeeded: ${result.succeededCount}, Failed: ${result.failedCount}`);
  console.log('Remaining credits:', result.remainingCredits);
}

curl -X POST https://api.screenshotly.dev/v1/capture/batch \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://google.com",
      "https://github.com"
    ],
    "options": {
      "format": "png",
      "viewport_width": 1280,
      "viewport_height": 800,
      "full_page": true
    }
  }'

response = requests.post(
    'https://api.screenshotly.dev/v1/capture/batch',
    headers={
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
    },
    json={
        'urls': [
            'https://example.com',
            'https://google.com',
            'https://github.com'
        ],
        'options': {
            'format': 'png',
            'viewport_width': 1280,
            'full_page': True
        }
    }
)

Response format

The batch response includes individual results for each URL and summary counts:

{
  "success": true,
  "data": [
    {
      "_id": "67b8a1c2d3e4f5a6b7c8d9e0",
      "url": "https://example.com",
      "status": "pending"
    },
    {
      "_id": "67b8a1c2d3e4f5a6b7c8d9e1",
      "url": "https://google.com",
      "status": "pending"
    }
  ],
  "count": 2,
  "succeededCount": 2,
  "failedCount": 0,
  "remainingCredits": 4998
}

Batch screenshots are processed asynchronously via a background queue. Use the screenshot status endpoint or webhooks to track completion.

Limits

Maximum 50 URLs per batch request
The API validates that you have enough monthly credits for the entire batch before processing
If you don’t have enough credits, the entire request is rejected

Shared options

All options passed in the options object apply to every URL in the batch. Supported options are the same as the capture endpoint:

Option	Type	Default	Description
`format`	string	png	Output format (png, jpeg, webp, pdf)
`viewport_width`	integer	1280	Viewport width in pixels
`viewport_height`	integer	1024	Viewport height in pixels
`full_page`	boolean	false	Capture full scrollable page
`delay`	integer	0	Delay in milliseconds
`device_scale_factor`	number	1	Device pixel ratio

Handling large batches

For more than 50 URLs, break them into chunks:

const allUrls = [/* hundreds of URLs */];
const chunkSize = 50;

for (let i = 0; i < allUrls.length; i += chunkSize) {
  const chunk = allUrls.slice(i, i + chunkSize);
  const result = await client.captureBatch({
    urls: chunk,
    options: { format: 'png', viewport_width: 1280 }
  });

  console.log(`Batch ${Math.floor(i / chunkSize) + 1}: ${result.succeededCount} queued, ${result.failedCount} failed`);
}

Credits

Each URL in a batch consumes one screenshot credit. A batch of 10 URLs uses 10 credits. Failed captures are automatically refunded. See the batch capture API reference for full endpoint details.

Getting started

Capture options

Advanced

Integrations

Account

Basic batch request

Response format

Limits

Shared options

Handling large batches

Credits

​Basic batch request

​Response format

​Limits

​Shared options

​Handling large batches

​Credits

Basic batch request

Response format

Limits

Shared options

Handling large batches

Credits