Batch Screenshot Operations API

Process multiple screenshots in a single API request. Capture up to 100 URLs simultaneously with shared configuration for efficient bulk screenshot generation and consistent results across all captures.

POST

/v1/screenshots/batch

Create multiple screenshot jobs in a single request. Apply the same configuration options to all URLs for consistent results.

Base URL: https://www.snapshotai.dev

Batch Processing

Batch requests create multiple jobs simultaneously. Each screenshot is processed independently and asynchronously. Use GET /v1/screenshots/:id to check individual job status.

Limits & Quota

• Maximum 100 URLs per batch request
• Batch count is checked against your monthly quota before processing
• If insufficient quota, the entire batch is rejected (no partial processing)
• Each successful job counts toward your usage limit

Request Body

urlsarray<string>Required

Array of URLs to capture. Minimum 1, maximum 100 URLs per request.

Example: ["https://example.com", "https://another-site.com"]

optionsobjectOptional

Screenshot options to apply to all URLs in the batch. Same options as single screenshot endpoint.

Example: { "viewport_width": 1920, "format": "png", "full_page": true }

Examples

Basic Batch Request

cURL•bash

curl -X POST https://www.snapshotai.dev/api/v1/screenshots/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://another-site.com",
      "https://third-website.com"
    ]
  }'

Batch with Options

cURL•bash

curl -X POST https://www.snapshotai.dev/api/v1/screenshots/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://another-site.com",
      "https://third-website.com"
    ],
    "options": {
      "viewport_width": 1920,
      "viewport_height": 1080,
      "format": "jpeg",
      "image_quality": 85,
      "full_page": true,
      "block_ads": true,
      "block_cookie_banners": true,
      "delay": 2000
    }
  }'

JavaScript / Node.js

javascript

const urls = [
  'https://example.com',
  'https://another-site.com',
  'https://third-website.com'
];

const response = await fetch('https://www.snapshotai.dev/api/v1/screenshots/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    urls,
    options: {
      viewport_width: 1920,
      viewport_height: 1080,
      format: 'png',
      full_page: true,
      block_ads: true
    }
  })
});

const data = await response.json();

console.log(`Created ${data.total} screenshot jobs`);
console.log(`Successful: ${data.successful}`);
console.log(`Failed: ${data.failed}`);

// Poll each screenshot until completed
for (const screenshot of data.screenshots) {
  console.log(`Job ${screenshot.id}: ${screenshot.status}`);
}

Python

python

import requests

urls = [
    "https://example.com",
    "https://another-site.com",
    "https://third-website.com"
]

response = requests.post(
    "https://www.snapshotai.dev/api/v1/screenshots/batch",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "urls": urls,
        "options": {
            "viewport_width": 1920,
            "viewport_height": 1080,
            "format": "png",
            "full_page": True,
            "block_ads": True
        }
    }
)

data = response.json()

print(f"Created {data['total']} screenshot jobs")
print(f"Successful: {data['successful']}")
print(f"Failed: {data['failed']}")

# Process each screenshot
for screenshot in data['screenshots']:
    print(f"Job {screenshot['id']}: {screenshot['status']}")

Success Response - All Jobs Created

200 OKapplication/json

{
  "screenshots": [
    {
      "id": "scr_2nX8Kp9mJ4dL7qR",
      "url_to_capture": "https://example.com",
      "status": "pending",
      "created_at": "2025-11-04T23:30:15.123Z"
    },
    {
      "id": "scr_9pK2mN8xJ7fH3wQ",
      "url_to_capture": "https://another-site.com",
      "status": "pending",
      "created_at": "2025-11-04T23:30:15.234Z"
    },
    {
      "id": "scr_4jR5wT3yH6bN1cD",
      "url_to_capture": "https://third-website.com",
      "status": "pending",
      "created_at": "2025-11-04T23:30:15.345Z"
    }
  ],
  "total": 3,
  "successful": 3,
  "failed": 0,
  "estimated_time": "30-90s"
}

Partial Failure Response

If some jobs fail to enqueue (rare queue system issues), you'll receive a response with details:

200 OKapplication/json

{
  "screenshots": [
    {
      "id": "scr_2nX8Kp9mJ4dL7qR",
      "url_to_capture": "https://example.com",
      "status": "pending",
      "created_at": "2025-11-04T23:30:15.123Z"
    },
    {
      "id": "scr_9pK2mN8xJ7fH3wQ",
      "url_to_capture": "https://another-site.com",
      "status": "failed",
      "created_at": "2025-11-04T23:30:15.234Z"
    }
  ],
  "total": 2,
  "successful": 1,
  "failed": 1,
  "failed_jobs": [
    {
      "id": "scr_9pK2mN8xJ7fH3wQ",
      "url": "https://another-site.com",
      "error": "Failed to enqueue job - queue system unavailable"
    }
  ],
  "warning": "Some jobs failed to enqueue - queue system may be experiencing issues",
  "estimated_time": "30-90s"
}

Response Fields

• screenshots - Array of created screenshot jobs
• total - Total number of jobs created
• successful - Jobs successfully enqueued
• failed - Jobs that failed to enqueue
• failed_jobs - Details of failed jobs (only if failures occurred)

Best Practices

• Check quota first - Ensure you have sufficient quota before large batches
• Use consistent options - All URLs in a batch receive the same configuration
• Poll individually - Each screenshot completes at different times, poll them separately
• Handle partial failures - Check the failed_jobs array
• Consider webhooks - For large batches, webhooks are more efficient than polling
• Batch similar URLs - Group URLs that need similar processing times

Common Use Cases

Competitor Analysis

Capture screenshots of multiple competitor websites for comparison and analysis.

Site Monitoring

Monitor multiple pages of your website for visual changes or issues.

Portfolio Archives

Archive multiple client websites or project pages with consistent settings.

Testing Workflows

Test your application across multiple pages or environments simultaneously.

Processing Time

Batch jobs are processed in parallel across our infrastructure. Each screenshot typically completes in 10-60 seconds, but batches don't take significantly longer than single requests due to parallel processing.

curl -X POST https://www.snapshotai.dev/api/v1/screenshots/batch \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": [ "https://example.com", "https://another-site.com", "https://third-website.com" ], "options": { "viewport_width": 1920, "viewport_height": 1080, "format": "jpeg", "image_quality": 85, "full_page": true, "block_ads": true, "block_cookie_banners": true, "delay": 2000 } }'

import requests urls = [ "https://example.com", "https://another-site.com", "https://third-website.com" ] response = requests.post( "https://www.snapshotai.dev/api/v1/screenshots/batch", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, json={ "urls": urls, "options": { "viewport_width": 1920, "viewport_height": 1080, "format": "png", "full_page": True, "block_ads": True } } ) data = response.json() print(f"Created {data['total']} screenshot jobs") print(f"Successful: {data['successful']}") print(f"Failed: {data['failed']}") # Process each screenshot for screenshot in data['screenshots']: print(f"Job {screenshot['id']}: {screenshot['status']}")

{ "screenshots": [ { "id": "scr_2nX8Kp9mJ4dL7qR", "url_to_capture": "https://example.com", "status": "pending", "created_at": "2025-11-04T23:30:15.123Z" }, { "id": "scr_9pK2mN8xJ7fH3wQ", "url_to_capture": "https://another-site.com", "status": "pending", "created_at": "2025-11-04T23:30:15.234Z" }, { "id": "scr_4jR5wT3yH6bN1cD", "url_to_capture": "https://third-website.com", "status": "pending", "created_at": "2025-11-04T23:30:15.345Z" } ], "total": 3, "successful": 3, "failed": 0, "estimated_time": "30-90s" }

{ "screenshots": [ { "id": "scr_2nX8Kp9mJ4dL7qR", "url_to_capture": "https://example.com", "status": "pending", "created_at": "2025-11-04T23:30:15.123Z" }, { "id": "scr_9pK2mN8xJ7fH3wQ", "url_to_capture": "https://another-site.com", "status": "failed", "created_at": "2025-11-04T23:30:15.234Z" } ], "total": 2, "successful": 1, "failed": 1, "failed_jobs": [ { "id": "scr_9pK2mN8xJ7fH3wQ", "url": "https://another-site.com", "error": "Failed to enqueue job - queue system unavailable" } ], "warning": "Some jobs failed to enqueue - queue system may be experiencing issues", "estimated_time": "30-90s" }