> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch processing

> Capture multiple webpage screenshots in a single API call with uniform settings.

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

<CodeGroup>
  ```javascript JavaScript SDK theme={null}
  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);
  }
  ```

  ```bash cURL theme={null}
  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
      }
    }'
  ```

  ```python Python theme={null}
  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
          }
      }
  )
  ```
</CodeGroup>

## Response format

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

```json theme={null}
{
  "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
}
```

<Note>
  Batch screenshots are processed asynchronously via a background queue. Use the [screenshot status](/api-reference/screenshot-status) endpoint or [webhooks](/guides/webhooks) to track completion.
</Note>

## 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](/api-reference/capture-screenshot):

| 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:

```javascript theme={null}
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](/api-reference/batch-capture) for full endpoint details.