API Documentation

Everything you need to capture website screenshots programmatically.

Getting Started

Start capturing screenshots in three simple steps.

1

Create an account

Sign up for a free account. No credit card required.

2

Copy your API key

Go to your dashboard and copy your API key.

3

Make your first request

Use the example below to capture your first screenshot.

First request
curl -X GET "https://api.fastscreenshotapi.com/v1/screenshot?url=https://example.com&response_type=binary" \
  -H "X-Api-Key: your_api_key" \
  --output screenshot.png

Authentication

All API requests require authentication. There are three ways to authenticate.

X-Api-Key header Recommended

Pass your API key via the X-Api-Key header.

bash
curl "https://api.fastscreenshotapi.com/v1/screenshot?url=https://example.com" \
  -H "X-Api-Key: fsa_your_api_key"

Query parameter

Pass your API key as an api_key query parameter. Useful for embedding in <img> tags.

html
<img src="https://api.fastscreenshotapi.com/v1/screenshot?url=https://example.com&api_key=fsa_your_api_key" />

Bearer token

For dashboard API endpoints, use a Bearer token in the Authorization header.

bash
curl "https://api.fastscreenshotapi.com/v1/account" \
  -H "Authorization: Bearer your_access_token"

Screenshot Endpoint

GET /v1/screenshot

Pass parameters as query strings. Ideal for embedding in <img> tags.

bash
curl "https://api.fastscreenshotapi.com/v1/screenshot?url=https://example.com&format=webp&full_page=true&response_type=binary" \
  -H "X-Api-Key: fsa_your_api_key" \
  --output screenshot.webp

POST /v1/screenshot

Send parameters as a JSON body for full control over all options.

bash
curl -X POST "https://api.fastscreenshotapi.com/v1/screenshot" \
  -H "X-Api-Key: fsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "webp",
    "full_page": true,
    "mobile": true,
    "response_type": "binary"
  }' \
  --output screenshot.webp

Parameters

All parameters for the screenshot endpoint.

ParameterTypeDefaultPlanDescription
urlstringrequiredFreeURL to capture
formatstringpngFreeOutput format: png, jpeg, webp, pdf
qualityinteger85FreeImage quality for JPEG/WebP (1-100)
full_pagebooleanfalseFreeCapture entire scrollable page
mobilebooleanfalseFreeUse a 390×844 mobile viewport and mobile user agent (desktop captures use 1920×1080)
dark_modebooleanfalseFreeRender the page with prefers-color-scheme: dark
wait_forstring—FreeCSS selector to wait for, or load / domcontentloaded / networkidle (max 500 chars). Never fails the request: after the wait the screenshot is taken anyway
wait_for_timeoutinteger10000FreeMax wait for wait_for in ms (1000-60000 accepted; the wait is capped at 10000)
block_cookie_bannersbooleantrueFreeAuto-dismiss cookie/GDPR banners
scroll_to_bottombooleantrueFreeAuto-scroll for lazy-loaded content
delayinteger3000FreeExtra delay after page load in ms (0-10000)
cache_ttlinteger86400FreeCache duration in seconds (0 = no cache, max 604800)
response_typestringurlFreeResponse format: url, binary, json
viewport_widthinteger1920Starter+Viewport width in px (320-3840). Ignored when mobile=true
viewport_heightinteger1080Starter+Viewport height in px (240-2160). Ignored when mobile=true
device_scale_factornumber1Starter+Device pixel ratio, 1-3 (2 = Retina). Very large outputs are scaled down to fit a 50-megapixel budget
custom_cssstring—Starter+CSS injected before capture (max 5000 chars)
hide_selectorsstring[]—Starter+CSS selectors to hide before capture (max 10, each max 200 chars)
custom_headersobject—Pro+HTTP headers as name → value (max 10, values max 500 chars). Sent only to the target page's own origin
cookiesobject[]—Pro+Cookies as {name, value, domain?} (max 20). Scoped to the target host or a parent domain of it
htmlstring—Starter+HTML to render instead of URL (max 1MB, POST only)
webhook_urlstring—Starter+URL for async result delivery (async endpoint only)
webhook_secretstring—Starter+HMAC-SHA256 secret for webhook signature verification
upload_toobject—Pro+External S3/R2 storage config (async endpoint only)
geostring—Starter+Country code for geo-targeted screenshot (e.g., US, DE, JP). Uses managed proxy or BYOP.
proxy_config_idinteger—Starter+ID of saved proxy config to use (from /dashboard/proxies)

Plan labels show the cheapest plan that accepts a parameter; a lower plan gets 403 FEATURE_RESTRICTED. Common ad and tracker networks are blocked on every capture, so there is no ad-blocking option to set. See Render options for how viewport, CSS, waiting, cookies and headers behave.

Render Options

Control the browser before capture: viewport size, pixel density, color scheme, injected styles, what to wait for, and the cookies and headers the page sees.

POST /v1/screenshot and POST /v1/screenshot/async accept every option below. GET /v1/screenshot accepts viewport_width, viewport_height, device_scale_factor and dark_mode. The batch endpoint applies viewport_width and viewport_height to every URL.

viewport_width / viewport_height
Desktop captures default to 1920×1080. Width 320–3840 px, height 240–2160 px; send one and the other keeps its default. With mobile=true the 390×844 mobile viewport is used and both are ignored.
device_scale_factor
1 to 3 (2 for Retina). The image is that many times wider and taller than the viewport. Very large renders are scaled down to stay within a 50-megapixel output budget.
dark_mode
Renders with prefers-color-scheme: dark. Pages without dark styles look the same as usual.
custom_css
Up to 5,000 characters, injected before capture. Applied even when the page has a strict Content-Security-Policy.
hide_selectors
Up to 10 CSS selectors, 200 characters each. Every match gets display: none. An invalid selector is skipped without affecting the others.
wait_for
A CSS selector, or load, domcontentloaded or networkidle. The wait lasts up to wait_for_timeout, capped at 10 seconds. It never fails the request: if the element does not appear, the screenshot is taken anyway.
custom_headers
Up to 10 headers, values up to 500 characters. Sent only with requests to the target page's own origin (scheme, host and port), never to third-party hosts.
cookies
Up to 20 cookies as {name, value, domain}. Without domain the cookie is set for the target host. A domain must be the target host or a parent domain of it; any other cookie is dropped.

Custom viewport and Retina Starter+

A 1280×800 viewport at device_scale_factor 2 returns a 2560×1600 image.

cURL
curl -X POST "https://api.fastscreenshotapi.com/v1/screenshot" \
  -H "X-Api-Key: fsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "viewport_width": 1280,
    "viewport_height": 800,
    "device_scale_factor": 2,
    "response_type": "binary"
  }' \
  --output screenshot.png

Custom CSS and hidden elements Starter+

custom_css is injected before capture, and every hide_selectors match gets display: none.

cURL
curl -X POST "https://api.fastscreenshotapi.com/v1/screenshot" \
  -H "X-Api-Key: fsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "custom_css": "body { font-family: Georgia, serif; }",
    "hide_selectors": [
      "#chat-widget",
      ".newsletter-popup"
    ],
    "response_type": "binary"
  }' \
  --output clean.png

Wait for an element All plans

Waits up to wait_for_timeout (capped at 10 seconds) for the selector, then captures whether it appeared or not.

cURL
curl -X POST "https://api.fastscreenshotapi.com/v1/screenshot" \
  -H "X-Api-Key: fsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "wait_for": "#chart-loaded",
    "wait_for_timeout": 8000,
    "response_type": "binary"
  }' \
  --output dashboard.png

Cookies and custom headers Pro+

Headers are sent only to the target page's own origin. Cookies are scoped to the target host or its parent domain.

cURL
curl -X POST "https://api.fastscreenshotapi.com/v1/screenshot" \
  -H "X-Api-Key: fsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/account",
    "custom_headers": {
      "Accept-Language": "de-DE"
    },
    "cookies": [
      {
        "name": "session",
        "value": "your_session_token",
        "domain": "example.com"
      }
    ],
    "response_type": "binary"
  }' \
  --output account.png

Response Types

Control the response format with the response_type parameter.

url (default)

Uploads the screenshot to our managed Cloudflare R2 bucket and returns a signed URL valid for 7 days. The object is auto-deleted after 7 days. Best for embedding in dashboards, sharing links, or decoupling capture from delivery.

binary

Returns raw image data with the appropriate Content-Type header (image/png, image/jpeg, or image/webp). Pass response_type=binary if you want bytes inline instead of a URL.

json

Returns a JSON object with a base64-encoded screenshot and metadata.

response_type=json
{
  "success": true,
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",
  "format": "png",
  "request_id": "req_abc123",
  "timing": { "total_ms": 1240 },
  "bytes": 284729,
  "cached": false
}

url — example response

Signed URL is valid for 7 days. After expiry, the object is gone — keep your own copy if you need longer retention.

response_type=url
{
  "success": true,
  "url": "https://api.fastscreenshotapi.com/v1/screenshot/download?path=...&expires=1700000000&signature=...",
  "format": "png",
  "request_id": "req_abc123",
  "expires_at": "2026-11-03T12:00:00+00:00",
  "timing": { "total_ms": 1240 },
  "bytes": 284729,
  "cached": false
}

Response Headers

Every response includes these headers with request metadata.

HeaderDescription
X-Request-IdUnique request identifier for debugging and support
X-RateLimit-LimitMaximum requests allowed per minute
X-RateLimit-RemainingRemaining requests in the current minute window
X-RateLimit-ResetUnix timestamp when the rate limit resets
X-Quota-LimitTotal monthly screenshot quota for your plan
X-Quota-UsedScreenshots used in the current billing period
X-CacheCache status: HIT (served from cache) or MISS (fresh capture)

Caching

Screenshots are cached to improve performance and reduce redundant captures.

  • Default cache duration is 24 hours (86400 seconds).
  • Same URL + same parameters = instant cache hit (~300ms response time).
  • Cached requests do not count against your monthly quota.
  • Use cache_ttl=0 to disable caching. Maximum TTL is 7 days (604800 seconds).

Anti-bot Bypass

Many websites use bot detection (Cloudflare, DataDome, PerimeterX) that blocks headless browsers. On Starter+ plans, FastScreenshotAPI automatically retries blocked captures through residential networks.

  • Residential IP addresses, not datacenter IPs.
  • Automatic — no extra parameters needed.

Plan Requirements

Some features require a specific plan. If you use a restricted feature on a lower plan, the API returns a 403 FEATURE_RESTRICTED error.

PlanFeatures Included
FreeCore parameters: url, format, quality, full_page, mobile, dark_mode, wait_for, wait_for_timeout, block_cookie_banners, scroll_to_bottom, delay, cache_ttl, response_type
Starter++ viewport_width, viewport_height, device_scale_factor, custom_css, hide_selectors, html, async endpoint, batch endpoint, webhook_url, webhook_secret, geo, proxy_config_id, anti-bot bypass
Pro++ custom_headers, cookies, upload_to (your own S3/R2 bucket)
Business+ Priority rendering queue

Code Examples

Complete, copy-pasteable examples in popular languages.

cURL
curl -X POST "https://api.fastscreenshotapi.com/v1/screenshot" \
  -H "X-Api-Key: fsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "webp",
    "quality": 90,
    "full_page": true,
    "block_cookie_banners": true,
    "response_type": "binary"
  }' \
  --output screenshot.webp
Node.js
const response = await fetch("https://api.fastscreenshotapi.com/v1/screenshot", {
  method: "POST",
  headers: {
    "X-Api-Key": "fsa_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    format: "webp",
    quality: 90,
    full_page: true,
    block_cookie_banners: true,
    response_type: "binary",
  }),
});

const buffer = await response.arrayBuffer();
const fs = await import("fs");
fs.writeFileSync("screenshot.webp", Buffer.from(buffer));

console.log("Request ID:", response.headers.get("X-Request-Id"));
console.log("Cached:", response.headers.get("X-Cache"));
Python
import requests

response = requests.post(
    "https://api.fastscreenshotapi.com/v1/screenshot",
    headers={"X-Api-Key": "fsa_your_api_key"},
    json={
        "url": "https://example.com",
        "format": "webp",
        "quality": 90,
        "full_page": True,
        "block_cookie_banners": True,
        "response_type": "binary",
    },
)

with open("screenshot.webp", "wb") as f:
    f.write(response.content)

print("Request ID:", response.headers["X-Request-Id"])
print("Cached:", response.headers["X-Cache"])
PHP
$ch = curl_init("https://api.fastscreenshotapi.com/v1/screenshot");

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-Api-Key: fsa_your_api_key",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "format" => "webp",
        "quality" => 90,
        "full_page" => true,
        "block_cookie_banners" => true,
        "response_type" => "binary",
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

file_put_contents("screenshot.webp", $response);
HTML (img tag)
<!-- Direct embedding — uses your API key as a query parameter -->
<img
  src="https://api.fastscreenshotapi.com/v1/screenshot?url=https://example.com&format=webp&response_type=binary&api_key=fsa_your_api_key"
  alt="Screenshot of example.com"
  loading="lazy"
/>

Async Screenshots

Use async screenshots for heavy pages, batch processing, serverless environments, or when you need webhook notifications.

POST /v1/screenshot/async

Submit a screenshot job and receive a job ID. The screenshot will be processed in the background.

Async request
curl -X POST https://api.fastscreenshotapi.com/v1/screenshot/async \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "full_page": true,
    "webhook_url": "https://your-server.com/webhook",
    "webhook_secret": "your-hmac-secret"
  }'

Response (202)

Async response
{
    "job_id": "job_cZ1DADXGyzNM",
    "status": "queued",
    "status_url": "https://api.fastscreenshotapi.com/v1/screenshot/status/job_cZ1DADXGyzNM",
    "estimated_time_ms": 30000
}

Checking Status

Use GET /v1/screenshot/status/{jobId} to check the status of a job. A job can be in one of three statuses:

  • queued — the job is waiting to be picked up by a worker.
  • processing — the browser is loading the page and capturing the screenshot.
  • completed / failed — the job finished successfully or encountered an error.

Polling vs Webhooks

For production use, we recommend webhooks — they deliver results instantly without repeated API calls. Use polling only for testing or when webhooks are not feasible.

Webhook Verification

Webhooks are signed with HMAC-SHA256. The signature is sent in the X-Webhook-Signature header as a hex digest of the raw request body. Compute the HMAC over the raw bytes (not re-serialized JSON), compare in constant time, and only then process the payload.

Node.js
const crypto = require('crypto');
const express = require('express');

// Verify against the RAW body bytes — re-serializing parsed JSON
// will not reproduce the exact signed payload.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = Buffer.from(req.get('X-Webhook-Signature') || '', 'utf8');
  const expected = Buffer.from(
    crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex'),
    'utf8',
  );

  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(signature, expected)
  ) {
    return res.status(401).send('Invalid signature');
  }

  const { job_id, status, screenshot_url } = JSON.parse(req.body.toString('utf8'));
  console.log(`Job ${job_id}: ${status}`);
  res.status(200).send('OK');
});
Python
import hmac, hashlib, os

@app.route('/webhook', methods=['POST'])
def webhook():
    # request.data holds the raw body bytes that were signed
    signature = request.headers.get('X-Webhook-Signature', '')
    expected = hmac.new(
        os.environ['WEBHOOK_SECRET'].encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    data = request.json
    print(f"Job {data['job_id']}: {data['status']}")
    return 'OK', 200

HTML Rendering

Render custom HTML as a screenshot — perfect for invoices, OG images, email templates, and reports.

  • Only available via POST (not GET).
  • html and url are mutually exclusive — provide one or the other.
  • Maximum HTML size: 1 MB.
  • Works with all response_type options (binary, json, url).
  • Runs in an isolated browser context for security.
HTML rendering
curl -X POST https://api.fastscreenshotapi.com/v1/screenshot \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body><h1>Invoice #123</h1><p>Total: $500</p></body></html>",
    "format": "png",
    "response_type": "json"
  }'

External Storage Upload

By default we host every screenshot in our managed Cloudflare R2 bucket for 7 days and return a signed url. Pass an upload_to block to deliver the image straight to your own S3-compatible bucket — useful for longer retention, your own jurisdiction, or skipping the round-trip through our storage.

  • Supported providers: AWS S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, MinIO, Wasabi.
  • Minimum permissions: s3:PutObject, s3:PutObjectAcl.
  • Available with async screenshots.
Upload to S3
curl -X POST https://api.fastscreenshotapi.com/v1/screenshot/async \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "upload_to": {
      "type": "s3",
      "bucket": "my-screenshots",
      "region": "eu-west-1",
      "access_key": "AKIA...",
      "secret_key": "...",
      "path": "screenshots/"
    }
  }'

For one-time bucket configuration, visit your dashboard storage settings.

MCP Server

Connect AI agents to take screenshots via MCP protocol.

Configuration

The MCP server is hosted at https://api.fastscreenshotapi.com/v1/mcp. Point any MCP client that supports remote servers at it and pass your API key in the X-Api-Key header.

MCP client config
{
  "mcpServers": {
    "fastscreenshot": {
      "url": "https://api.fastscreenshotapi.com/v1/mcp",
      "headers": {
        "X-Api-Key": "fsa_your_api_key"
      }
    }
  }
}

Available tools

  • take_screenshot — capture a URL or render HTML
  • batch_screenshots — submit several URLs as async jobs
  • check_job_status — check the status of an async or batch job
  • get_usage — show quota and usage for the current billing period

See full MCP documentation →

OpenAPI Spec

Download the machine-readable API description and auto-generate a typed SDK in any language.

OpenAPI 3.0 specification

https://api.fastscreenshotapi.com/openapi.json

Download JSON
  • Import into Postman, Insomnia, or any API client
  • Auto-generate SDK in Node.js, Python, PHP, Go, Ruby, Java, C#
  • Import into Swagger UI for interactive docs

SDK generation guide →

Error Codes

When a request fails, the API returns a JSON error response with a machine-readable code, a human-readable message, and a suggestion to help you resolve the issue.

CodeHTTP StatusDescriptionSuggestion
INVALID_URL400URL is malformed or unreachableProvide a valid URL starting with http:// or https://
INVALID_PARAMS400Validation errorCheck parameter values against docs
UNAUTHORIZED401Missing or invalid API keyPass API key via X-Api-Key header
ACCOUNT_SUSPENDED403Account suspendedContact support
EMAIL_NOT_VERIFIED403Account email not confirmed yetOpen the verification link we emailed you, or resend it from the dashboard
PRIVATE_IP403URL resolves to private IPOnly publicly accessible URLs allowed
FEATURE_RESTRICTED403Feature not available on your planUpgrade to a higher plan to access this feature
QUOTA_EXCEEDED429Monthly quota reachedUpgrade plan for more screenshots
RATE_LIMITED429Too many requests per minuteWait and retry, check X-RateLimit-Reset header
PAGE_NOT_FOUND422Target URL returned 404Check if the URL is correct
SSL_ERROR422Target has SSL issuesCheck target site's SSL certificate
BLOCKED_BY_SITE422Target blocked the requestSite has bot protection
SCREENSHOT_TIMEOUT504Page load timeoutRetry, or add a short delay for slow pages
SCREENSHOT_FAILED502Capture failedRetry the request
SERVICE_OVERLOADED503All containers busyRetry with exponential backoff
INTERNAL_ERROR500Server errorContact support

Error Response Format

Every error response follows the same structure:

json
{
    "error": true,
    "code": "SERVICE_OVERLOADED",
    "message": "All rendering capacity is busy.",
    "suggestion": "Retry with exponential backoff.",
    "documentation_url": "https://fastscreenshotapi.com/docs#error-codes"
}