Batch Screenshots

The batch endpoint lets you capture multiple screenshots in a single request, with support for both synchronous and asynchronous processing.

Endpoint

POST https://api.renderscreenshot.com/v1/batch

Authentication

Include your API key in the Authorization header:

Authorization: Bearer rs_live_xxxxx

Simple Batch Request

Apply the same options to all URLs:

{
  "urls": [
    "https://example1.com",
    "https://example2.com",
    "https://example3.com"
  ],
  "options": {
    "preset": "og_card",
    "block": { "ads": true }
  },
  "concurrency": 3
}

Advanced Batch Request

Specify different options per URL:

{
  "requests": [
    { "url": "https://example1.com", "preset": "og_card" },
    { "url": "https://example2.com", "preset": "full_page" },
    { "url": "https://example3.com", "viewport": { "width": 1920 } }
  ],
  "webhook": {
    "url": "https://your-server.com/webhook"
  }
}

Sync vs Async Processing

Synchronous (≤10 URLs without webhook): - Request blocks until all screenshots complete - Returns full results in response

Asynchronous (>10 URLs or webhook specified): - Returns immediately with job ID - Poll GET /v1/batch/:id for status - Or receive webhook on completion

Synchronous Response

{
  "id": "batch_abc123",
  "status": "completed",
  "results": [
    {
      "url": "https://example1.com",
      "status": "completed",
      "image": {
        "url": "https://cdn.renderscreenshot.com/abc.png",
        "width": 1200,
        "height": 630
      }
    },
    {
      "url": "https://example2.com",
      "status": "completed",
      "image": {
        "url": "https://cdn.renderscreenshot.com/def.png",
        "width": 1280,
        "height": 4500
      }
    },
    {
      "url": "https://example3.com",
      "status": "failed",
      "error": {
        "type": "target_error",
        "code": "timeout",
        "message": "Page failed to load within 30 seconds",
        "retryable": true
      }
    }
  ],
  "summary": {
    "total": 3,
    "completed": 2,
    "failed": 1
  },
  "usage": {
    "credits": 2,
    "remaining": 9997
  }
}

Asynchronous Response

Initial response:

{
  "id": "batch_abc123",
  "status": "processing",
  "total": 50,
  "progress": 0
}

Poll for status:

GET /v1/batch/batch_abc123

Webhook Integration

When a webhook is configured, you'll receive a POST request on completion:

{
  "event": "batch.completed",
  "batch_id": "batch_abc123",
  "status": "completed",
  "summary": {
    "total": 50,
    "completed": 48,
    "failed": 2
  },
  "results_url": "https://api.renderscreenshot.com/v1/batch/batch_abc123/results"
}

See Webhooks for configuration details.

Example

curl -X POST https://api.renderscreenshot.com/v1/batch \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://github.com",
      "https://stripe.com",
      "https://linear.app"
    ],
    "options": {
      "preset": "og_card"
    }
  }'

Rate Limits

Batch size limits vary by plan:

See Rate Limits for more details.