Batch Screenshots

The batch endpoint lets you capture multiple URLs in a single API call — up to 100 at a time. Instead of making 100 separate requests, you send one request with an array of URLs and shared capture options.

This is ideal for:

Generating thumbnails for a list of websites (directories, catalogs)
Running visual regression tests across multiple pages
Monitoring a set of competitor websites
Archiving multiple pages at once

Note

Batch screenshots require a Pro plan or above.

Create Batch Screenshots

POST /v1/screenshots/batch

Queues screenshots for all URLs in the request. Returns a 202 Accepted response with an array of screenshot objects, each in pending status. Every screenshot is processed independently.

Parameters

Parameter	Type	Required	Description
`urls`	array	Yes	Array of URLs to capture. Minimum 1, maximum 100.

All other parameters are shared across every URL in the batch. The following parameters are supported:

width, height, full_page, format, quality, device, dark_mode, block_ads, block_cookies, block_chats, delay, timeout, css, js, retina, resize_width, resize_height, stealth, omit_background, reduced_motion, user_agent, timezone, wait_for_selector, webhook_url.

Not supported in batch

These parameters work per-URL and are not available in batch requests: selector, click_selector, scroll_to, headers, cookies, hide_selectors, html, markdown, pdf_*, geolocation, proxy, cache_ttl, extract_metadata, response_type.

Example Request

curl -X POST https://api.screenshotrun.com/v1/screenshots/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://example.org",
      "https://example.net"
    ],
    "width": 1440,
    "format": "webp",
    "full_page": true
  }'

Response (202 Accepted)

{
  "data": [
    {
      "id": "550e8400-...",
      "status": "pending",
      "url": "https://example.com",
      "options": { ... },
      "created_at": "2026-03-09T10:30:00.000000Z",
      "links": { "self": "..." }
    },
    {
      "id": "660f9500-...",
      "status": "pending",
      "url": "https://example.org",
      "options": { ... },
      "created_at": "2026-03-09T10:30:00.000000Z",
      "links": { "self": "..." }
    },
    {
      "id": "770a0600-...",
      "status": "pending",
      "url": "https://example.net",
      "options": { ... },
      "created_at": "2026-03-09T10:30:00.000000Z",
      "links": { "self": "..." }
    }
  ],
  "total": 3
}

Processing & Completion

Each screenshot in the batch is processed independently. Some may complete faster than others depending on page complexity and load times.

You have two ways to know when screenshots are ready:

Polling: Check each screenshot by its id using GET /v1/screenshots/{id}.
Webhooks: Include webhook_url in the batch request. A separate webhook notification is sent for every screenshot that completes or fails.

Tip

Webhooks are recommended for batch requests — polling 100 screenshots individually is not efficient. See Webhooks for setup details.

Rate Limits & Quotas

Warning

Each URL in the batch counts as one screenshot toward your monthly quota. A batch of 50 URLs uses 50 screenshots from your plan.

Rate limits apply per-URL as well. If your plan allows 40 requests per minute and you send a batch of 50 URLs, the batch is accepted but some screenshots may be queued until rate limit capacity frees up.

Full Example with Webhooks

curl -X POST https://api.screenshotrun.com/v1/screenshots/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://stripe.com",
      "https://github.com",
      "https://vercel.com",
      "https://cloudflare.com"
    ],
    "width": 1280,
    "format": "webp",
    "full_page": true,
    "block_ads": true,
    "webhook_url": "https://yourapp.com/webhooks/screenshot"
  }'

Your webhook endpoint will receive 4 separate notifications — one for each screenshot as it completes.