API Documentation

Name: Screenshot API
Author: Screenshot API

Screenshot API provides a simple REST API for capturing website screenshots. No credit card required. Start making requests in seconds.

Getting Started

Capture your first screenshot in 3 simple steps:

Get your free API key from the get-api-key page
Make a request to the screenshot endpoint
Use the returned CDN URL (or redirect to download bytes)

bash

# Capture a screenshot
curl -X POST "https://api.screenshot-api.org/api/v1/screenshot" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com","format":"png","fullPage":false}'

Authentication

Authenticate your requests using an API key. You can pass it as a query parameter (convenience) or in headers (recommended):

bash

# Query parameter
curl "https://api.screenshot-api.org/api/v1/screenshot?url=...&key=YOUR_API_KEY"

# Authorization header
curl "https://api.screenshot-api.org/api/v1/screenshot?url=..." \
  -H "Authorization: Bearer YOUR_API_KEY"

# X-API-Key header
curl "https://api.screenshot-api.org/api/v1/screenshot?url=..." \
  -H "X-API-Key: YOUR_API_KEY"

API Reference

GET/api/v1/screenshot

Capture a screenshot using query parameters. Returns JSON by default; use redirect=1 to get a 302 to the image/PDF.

POST/api/v1/screenshot

Same as GET, but parameters are passed in the request body as JSON. Useful for complex configurations.

POST/api/v1/screenshot/batch

Capture multiple screenshots in a single request. Returns a batch ID for tracking progress.

Parameters

Basic parameters work on both GET (query string) and POST (JSON body). Advanced options like css, js, hideSelectors, geolocation, and pdf are POST-only.

Parameter	Type	Required	Description
`url`	string	Required	The URL to capture
`format`	"png" \| "jpeg" \| "webp" \| "pdf"	Optional	Output format (default: png)
`viewport.width`	number	Optional	Viewport width in pixels (POST JSON body). For GET use width.
`viewport.height`	number	Optional	Viewport height in pixels (POST JSON body). For GET use height.
`fullPage`	boolean	Optional	Capture the full scrollable page (default: false)
`deviceScaleFactor`	number	Optional	Device scale factor for retina (default: 1)
`waitUntil`	"load" \| "domcontentloaded" \| "networkidle0" \| "networkidle2"	Optional	Navigation wait strategy (default: networkidle2)
`quality`	number	Optional	Image quality for jpeg/webp (1-100)
`selector`	string	Optional	Capture a specific element (CSS selector). Not supported for PDF.
`waitForSelector`	string	Optional	Wait for a selector to appear before capture
`delayMs`	number	Optional	Extra delay (ms) after load, for late UI (default: 0)
`blockAds`	boolean	Optional	Block ads and trackers (default: true)
`blockCookieBanners`	boolean	Optional	Block cookie consent banners (default: true)
`darkMode`	boolean	Optional	Enable dark mode (default: false)
`hideSelectors`	string[]	Optional	Hide elements by CSS selectors (POST only)
`css`	string	Optional	Inject custom CSS before capture (POST only)
`js`	string	Optional	Inject custom JavaScript before capture (POST only)
`geolocation`	{ latitude, longitude, accuracy? }	Optional	Simulate geolocation (POST only)
`timezoneId`	string	Optional	Emulate timezone (e.g. America/Los_Angeles) (POST only)
`locale`	string	Optional	Set Accept-Language (e.g. en-US) (POST only)
`pdf`	object	Optional	PDF options (requires format=pdf) (POST only)
`cache`	boolean	Optional	Use cached version if available (default: true)
`cacheTTL`	number	Optional	Cache time-to-live in seconds (default: 86400)
`staleTTL`	number	Optional	Serve stale while revalidating, in seconds (default: 43200)
`timeoutMs`	number	Optional	Navigation timeout in milliseconds (default: 30000)
`redirect`	boolean	Optional	GET only: respond with 302 to the screenshot URL
`key`	string	Optional	Optional: API key via query string (convenience; headers recommended)

Code Examples

cURL

bash

curl -X POST "https://api.screenshot-api.org/api/v1/screenshot" \
	  -H "Authorization: Bearer YOUR_API_KEY" \
	  -H "Content-Type: application/json" \
	  -d '{
	    "url": "https://example.com",
	    "viewport": { "width": 1280, "height": 720 },
	    "format": "png",
	    "fullPage": true,
	    "blockAds": true
	  }'

JavaScript / Node.js

javascript

const response = await fetch('https://api.screenshot-api.org/api/v1/screenshot', {
	  method: 'POST',
	  headers: {
	    'Authorization': 'Bearer YOUR_API_KEY',
	    'Content-Type': 'application/json',
	  },
	  body: JSON.stringify({
	    url: 'https://example.com',
	    viewport: { width: 1280, height: 720 },
	    format: 'png',
	    fullPage: true,
	  }),
	});

const data = await response.json();
console.log(data.screenshotUrl);

Python

python

import requests

	response = requests.post(
	    'https://api.screenshot-api.org/api/v1/screenshot',
	    headers={'Authorization': 'Bearer YOUR_API_KEY'},
	    json={
	        'url': 'https://example.com',
	        'viewport': { 'width': 1280, 'height': 720 },
	        'format': 'png',
	        'fullPage': True,
	    }
	)

data = response.json()
print(data['screenshotUrl'])

Batch Screenshots

Capture multiple URLs in a single request. Perfect for bulk operations and automation.

bash

curl -X POST "https://api.screenshot-api.org/api/v1/screenshot/batch" \
	  -H "Authorization: Bearer YOUR_API_KEY" \
	  -H "Content-Type: application/json" \
	  -d '{
	    "urls": [
	      "https://example.com",
	      "https://example.org",
	      "https://example.net"
	    ],
	    "options": {
	      "viewport": { "width": 1280, "height": 720 },
	      "format": "png"
	    }
	  }'

Track batch progress via GET /api/v1/batch/:batchId or stream updates with SSE at GET /api/v1/batch/:batchId/stream

Error Handling

All errors return a consistent JSON response with an error code and message:

json

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": { "fieldErrors": { "url": ["Invalid URL"] } }
  },
  "meta": { "requestId": "req_..." }
}

Common Error Codes

Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing API key
`invalid_request`	400	Invalid request parameters or body
`rate_limited`	429	Rate limit exceeded (per-minute or monthly quota)
`quota_exceeded`	429	Monthly quota exceeded (batch pre-check)
`render_failed`	502	Failed to render the page
`selector_not_found`	422	The selector did not match any element

Rate Limits

Free plan limits (see pricing for higher tiers):

requests / minute

500

screenshots / month

Caching

faster repeat requests

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Quota-Remaining, X-Quota-Reset

Ready to get started?

Get your free API key and start capturing screenshots in seconds.

Get Free API Key