API Documentation
Everything you need to capture website screenshots programmatically.
Getting Started
Start capturing screenshots in three simple steps.
Create an account
Sign up for a free account. No credit card required.
Copy your API key
Go to your dashboard and copy your API key.
Make your first request
Use the example below to capture your first screenshot.
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.pngAuthentication
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.
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.
<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.
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.
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.webpPOST /v1/screenshot
Send parameters as a JSON body for full control over all options.
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.webpParameters
All parameters for the screenshot endpoint.
| Parameter | Type | Default | Plan | Description |
|---|---|---|---|---|
url | string | required | Free | URL to capture |
format | string | png | Free | Output format: png, jpeg, webp, pdf |
quality | integer | 85 | Free | Image quality for JPEG/WebP (1-100) |
full_page | boolean | false | Free | Capture entire scrollable page |
mobile | boolean | false | Free | Use a 390×844 mobile viewport and mobile user agent (desktop captures use 1920×1080) |
dark_mode | boolean | false | Free | Render the page with prefers-color-scheme: dark |
wait_for | string | — | Free | CSS 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_timeout | integer | 10000 | Free | Max wait for wait_for in ms (1000-60000 accepted; the wait is capped at 10000) |
block_cookie_banners | boolean | true | Free | Auto-dismiss cookie/GDPR banners |
scroll_to_bottom | boolean | true | Free | Auto-scroll for lazy-loaded content |
delay | integer | 3000 | Free | Extra delay after page load in ms (0-10000) |
cache_ttl | integer | 86400 | Free | Cache duration in seconds (0 = no cache, max 604800) |
response_type | string | url | Free | Response format: url, binary, json |
viewport_width | integer | 1920 | Starter+ | Viewport width in px (320-3840). Ignored when mobile=true |
viewport_height | integer | 1080 | Starter+ | Viewport height in px (240-2160). Ignored when mobile=true |
device_scale_factor | number | 1 | Starter+ | Device pixel ratio, 1-3 (2 = Retina). Very large outputs are scaled down to fit a 50-megapixel budget |
custom_css | string | — | Starter+ | CSS injected before capture (max 5000 chars) |
hide_selectors | string[] | — | Starter+ | CSS selectors to hide before capture (max 10, each max 200 chars) |
custom_headers | object | — | Pro+ | HTTP headers as name → value (max 10, values max 500 chars). Sent only to the target page's own origin |
cookies | object[] | — | Pro+ | Cookies as {name, value, domain?} (max 20). Scoped to the target host or a parent domain of it |
html | string | — | Starter+ | HTML to render instead of URL (max 1MB, POST only) |
webhook_url | string | — | Starter+ | URL for async result delivery (async endpoint only) |
webhook_secret | string | — | Starter+ | HMAC-SHA256 secret for webhook signature verification |
upload_to | object | — | Pro+ | External S3/R2 storage config (async endpoint only) |
geo | string | — | Starter+ | Country code for geo-targeted screenshot (e.g., US, DE, JP). Uses managed proxy or BYOP. |
proxy_config_id | integer | — | 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.
Custom CSS and hidden elements Starter+
custom_css is injected before capture, and every hide_selectors match gets display: none.
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.
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.
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.
{
"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.
{
"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.
| Header | Description |
|---|---|
X-Request-Id | Unique request identifier for debugging and support |
X-RateLimit-Limit | Maximum requests allowed per minute |
X-RateLimit-Remaining | Remaining requests in the current minute window |
X-RateLimit-Reset | Unix timestamp when the rate limit resets |
X-Quota-Limit | Total monthly screenshot quota for your plan |
X-Quota-Used | Screenshots used in the current billing period |
X-Cache | Cache 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=0to 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.
| Plan | Features Included |
|---|---|
| Free | Core 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 -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.webpconst 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"));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"])$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);<!-- 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.
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)
{
"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.
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');
});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', 200HTML Rendering
Render custom HTML as a screenshot — perfect for invoices, OG images, email templates, and reports.
- Only available via POST (not GET).
htmlandurlare mutually exclusive — provide one or the other.- Maximum HTML size: 1 MB.
- Works with all
response_typeoptions (binary, json, url). - Runs in an isolated browser context for security.
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.
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.
{
"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
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
- 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
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.
| Code | HTTP Status | Description | Suggestion |
|---|---|---|---|
INVALID_URL | 400 | URL is malformed or unreachable | Provide a valid URL starting with http:// or https:// |
INVALID_PARAMS | 400 | Validation error | Check parameter values against docs |
UNAUTHORIZED | 401 | Missing or invalid API key | Pass API key via X-Api-Key header |
ACCOUNT_SUSPENDED | 403 | Account suspended | Contact support |
EMAIL_NOT_VERIFIED | 403 | Account email not confirmed yet | Open the verification link we emailed you, or resend it from the dashboard |
PRIVATE_IP | 403 | URL resolves to private IP | Only publicly accessible URLs allowed |
FEATURE_RESTRICTED | 403 | Feature not available on your plan | Upgrade to a higher plan to access this feature |
QUOTA_EXCEEDED | 429 | Monthly quota reached | Upgrade plan for more screenshots |
RATE_LIMITED | 429 | Too many requests per minute | Wait and retry, check X-RateLimit-Reset header |
PAGE_NOT_FOUND | 422 | Target URL returned 404 | Check if the URL is correct |
SSL_ERROR | 422 | Target has SSL issues | Check target site's SSL certificate |
BLOCKED_BY_SITE | 422 | Target blocked the request | Site has bot protection |
SCREENSHOT_TIMEOUT | 504 | Page load timeout | Retry, or add a short delay for slow pages |
SCREENSHOT_FAILED | 502 | Capture failed | Retry the request |
SERVICE_OVERLOADED | 503 | All containers busy | Retry with exponential backoff |
INTERNAL_ERROR | 500 | Server error | Contact support |
Error Response Format
Every error response follows the same structure:
{
"error": true,
"code": "SERVICE_OVERLOADED",
"message": "All rendering capacity is busy.",
"suggestion": "Retry with exponential backoff.",
"documentation_url": "https://fastscreenshotapi.com/docs#error-codes"
}