Batch Screenshots

Capture screenshots of multiple URLs in one request. Returns base64-encoded images with per-URL success/error status.

POST/v1/batch/screenshot

Batch screenshots require a Growth+ plan. Max URLs per request depends on your plan.

Parameters

Parameter	Type	Default	Description
`urls`*	string[]	—	Array of URLs to screenshot. Min 1, max depends on plan.
`width`	number	1280	Viewport width in pixels. Min 320, max 3840.
`height`	number	720	Viewport height in pixels. Min 240, max 2160.
`format`	enum	png	Output format: png, jpeg, or webp.
`quality`	number	80	Compression quality for jpeg/webp. 1–100.
`full_page`	boolean	false	Capture full scrollable page height.
`dark_mode`	boolean	false	Emulate prefers-color-scheme: dark.
`block_ads`	boolean	false	Block ads, cookie banners, and trackers.
`delay`	number	0	Wait N ms after load before capture. Max 10000.
`wait_until`	enum	load	When to consider page loaded: load, domcontentloaded, networkidle.
`device`	string	—	Device preset (e.g. 'iPhone 14'). See device presets.

Plan limits

Plan	Max URLs per request
Free	❌ Not available
Starter	❌ Not available
Growth	10
Business	25
Enterprise	50

Response

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    {
      "url": "https://example.com",
      "success": true,
      "image_base64": "iVBORw0KGgo...",
      "content_type": "image/png",
      "size_bytes": 145230
    },
    {
      "url": "https://another.com",
      "success": true,
      "image_base64": "iVBORw0KGgo...",
      "content_type": "image/png",
      "size_bytes": 89400
    },
    {
      "url": "https://blocked-site.com",
      "success": false,
      "error": "Navigation timeout after 30000ms"
    }
  ]
}

Example

curl -X POST https://api.snapsharp.dev/v1/batch/screenshot \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://github.com",
      "https://linear.app",
      "https://vercel.com"
    ],
    "width": 1280,
    "format": "png",
    "dark_mode": true
  }'

// Each result is independent — one failing URL won't stop the others
const res = await fetch('https://api.snapsharp.dev/v1/batch/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    urls: ['https://github.com', 'https://linear.app'],
    width: 1280,
    dark_mode: true,
  }),
});

const data = await res.json();
for (const result of data.results) {
  if (result.success) {
    const buffer = Buffer.from(result.image_base64, 'base64');
    // save or process the image
  }
}

Errors

Code	Error	Description
400	`validation_error`	Invalid parameters or empty `urls` array
401	`unauthorized`	Missing or invalid API key
403	`plan_required`	Growth+ plan required
429	`rate_limited`	Rate limit exceeded
500	—	Internal server error