API Reference
Full documentation for the SnapshotFlow HTTP API. Base URL: https://api.snapshotflow.com
Authentication
Every request must include a valid API key. Create one in the dashboard.
Via header (recommended)
Via query param
Error Responses
All errors return JSON with a consistent shape:
| HTTP | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid parameters |
| 400 | INVALID_URL | URL is malformed or not http/https |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | BLOCKED | URL targets private/loopback address (SSRF) |
| 408 | TIMEOUT | Page load exceeded SCREENSHOT_TIMEOUT_MS |
| 422 | NAVIGATION_FAILED | Browser could not load the page |
| 502 | CAPTURE_FAILED | The browser failed while capturing, and the automatic retry on a fresh browser failed too |
| 422 | SELECTOR_NOT_FOUND | selector, click, or wait_for_selector not found |
| 429 | RATE_LIMITED | Too many requests — see retryAfter in response |
| 503 | POOL_EXHAUSTED | All browser slots busy, retry later |
Rate Limiting
Limits are applied per API key: 60 requests/minute.
{ "error": "RATE_LIMITED", "message": "Too many requests. Limit: 60 per minute.", "retryAfter": "23s" }
Caching
Every screenshot is cached by a SHA-256 hash of all capture parameters. Identical requests are served from cache without launching a browser. The X-Cache response header tells you whether the response was cached.
Use cache=false to bypass cache. TTL is set via CACHE_TTL_SECONDS (default: 3600).
GET /screenshot
Capture a screenshot of a URL or rendered HTML. Returns a binary image, base64 JSON, or metadata JSON depending on response_type.
Source
| Parameter | Type | Default | Description |
|---|---|---|---|
| url | string | — | Page URL to capture (http/https only). Required unless html is provided required* |
| html | string | — | Base64-encoded HTML to render instead of a URL optional |
Viewport
| Parameter | Type | Default | Description |
|---|---|---|---|
| width | integer | 1280 | Viewport width in px (100–3840) |
| height | integer | 800 | Viewport height in px (100–2160) |
| device_scale_factor | float | 1 | Device pixel ratio. Use 2 for retina |
| viewport_mobile | boolean | false | Enable mobile emulation (touch events, mobile meta tag) |
Capture
| Parameter | Type | Default | Description |
|---|---|---|---|
| format | enum | png | png · jpeg · webp · pdf |
| quality | integer | 80 | 1–100. Applies to jpeg and webp only |
| full_page | boolean | false | Capture the full scrollable height of the page |
| omit_background | boolean | false | Transparent background (PNG only) |
| selector | string | — | CSS selector — capture only that element |
| clip_x / clip_y | integer | 0 | Clip region top-left corner in px |
| clip_width / clip_height | integer | 0 | Clip region size (0 = disabled) |
| image_width / image_height | integer | 0 | Resize output (0 = no resize). Preserves aspect ratio |
Timing
| Parameter | Type | Default | Description |
|---|---|---|---|
| delay | integer ms | 0 | Extra wait after page load (max 10000ms) |
| wait_until | enum | networkidle2 | load · domcontentloaded · networkidle0 · networkidle2. With networkidle0 or networkidle2, the page HTML loads first, then the network gets up to 6 s to settle, so endless ad or analytics requests don't run into the timeout. Before the capture, web fonts and visible images get up to 3 s more. |
| wait_for_selector | string | — | Wait for this CSS selector to appear before capturing |
Emulation
| Parameter | Type | Default | Description |
|---|---|---|---|
| dark_mode | boolean | false | Force prefers-color-scheme: dark |
| reduced_motion | boolean | false | Enable prefers-reduced-motion: reduce |
| media_type | enum | screen | screen or print |
| timezone | string | — | IANA timezone, e.g. America/New_York |
| geolocation_latitude | float | — | Latitude (−90 to 90) |
| geolocation_longitude | float | — | Longitude (−180 to 180) |
| geolocation_accuracy | integer m | 100 | Geolocation accuracy radius in meters |
| user_agent | string | — | Custom User-Agent string |
| proxy | string | Coming soon | Managed proxy profile or explicit proxy endpoint for network-origin targeting (not live yet) |
| proxy_country | string | Coming soon | ISO country code for proxy-based local screenshots, e.g. DE or US (not live yet) |
| proxy_region | string | Coming soon | Region or state code for proxy targeting when supported (not live yet) |
| proxy_city | string | Coming soon | City-level proxy targeting when supported (not live yet) |
Injection & Interaction
| Parameter | Type | Description |
|---|---|---|
| headers | JSON string | Extra HTTP request headers, e.g. {"Authorization":"Bearer token"} |
| cookies | JSON string | Cookies array, e.g. [{"name":"s","value":"abc","domain":"example.com"}] |
| styles | string | CSS to inject into the page before capture |
| scripts | string | JavaScript to inject into the page before capture |
| hide_selectors | string | Comma-separated CSS selectors to hide (sets display:none) |
| click | string | CSS selector to click before capturing |
Blocking
| Parameter | Default | Description |
|---|---|---|
| block_ads | false | Block ads (powered by Ghostery) |
| block_trackers | false | Block trackers (powered by Ghostery) |
| block_cookie_banners | false | Block cookie consent banners |
| block_requests | — | Comma-separated URL patterns to block, e.g. analytics.js,hotjar.com |
These defaults apply to GET /screenshot. POST /batch and GET /diff block ads and cookie banners by default; pass false to turn it off.
PDF Options
| Parameter | Default | Description |
|---|---|---|
| pdf_print_background | false | Include background graphics in PDF |
| pdf_landscape | false | Landscape orientation |
| pdf_paper_format | a4 | a4 · a3 · a2 · a1 · letter · legal · tabloid |
Content Extraction
When extract_content=true, the response includes a content field alongside the image. Only available with response_type=json or base64.
| Parameter | Default | Description |
|---|---|---|
| extract_content | false | Extract page body as text |
| content_format | markdown | html · markdown · text |
Metadata Extraction
When metadata=true, the response includes a metadata object with title, OG tags, and favicon. Cache is bypassed for metadata requests.
Async / Webhook
| Parameter | Default | Description |
|---|---|---|
| async | false | Return 202 with job_id immediately, process in background |
| webhook_url | — | POST result JSON to this URL when the job completes |
Cache & Response
| Parameter | Default | Description |
|---|---|---|
| cache | true | Set to false to force a fresh screenshot |
| response_type | image | image — binary · json — metadata only · base64 — image in JSON |
Response Headers
| Header | Description |
|---|---|
| X-Cache | HIT if served from cache, MISS if freshly captured |
| Cache-Control | public, max-age=<CACHE_TTL_SECONDS> |
| ETag | Cache key SHA-256 hash |
POST /batch
Capture screenshots of up to 10 URLs in a single request. Processed in parallel. Each URL is captured independently — if one fails, others still complete. Ads and cookie banners are blocked by default. Set async: true to run the batch as a background job and follow its progress with GET /jobs/:id. What changed in this release: async batch jobs and ad blocking by default.
Request Body (JSON)
| Field | Type | Default | Description |
|---|---|---|---|
| urls | string[] | — | Array of URLs (1–10) required |
| format | enum | png | Output format for all URLs: png · jpeg · webp · pdf |
| width / height | integer | 1280 / 800 | Viewport dimensions |
| quality | integer | 80 | Compression quality (jpeg/webp) |
| full_page | boolean | false | Full page capture |
| block_ads | boolean | true | Block ads (powered by Ghostery) |
| block_cookie_banners | boolean | true | Block cookie consent banners |
| wait_until | enum | networkidle2 | load · domcontentloaded · networkidle0 · networkidle2. See Timing |
| response_type | enum | base64 | base64 — inline data URI · paths — storage path · image_urls — signed downloadUrl per result |
| async | boolean | false | Return 202 with a jobId immediately and process the batch in the background |
Response
Async Response (async: true)
Poll GET /jobs/:id for progress and per-URL results. Quota is charged per captured URL, as in the synchronous mode; cache hits are free.
403.
GET /diff
Pixel-level visual comparison between two URLs. Both pages are captured in parallel, then compared with pixelmatch. Changed pixels are highlighted in red in the diff image.
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| before | — | URL of the "before" state required |
| after | — | URL of the "after" state required |
| width / height | 1280 / 800 | Viewport dimensions for both captures |
| threshold | 0.1 | Sensitivity (0–1). Lower = more sensitive to subtle changes |
| block_ads | true | Block ads in both captures, so rotating ads don't count as changes |
| block_cookie_banners | true | Block cookie consent banners in both captures |
| wait_until | networkidle2 | Page readiness for both captures. See Timing |
| response_type | image | image — PNG · json — stats only · base64 — image + stats |
JSON Response (response_type=json)
GET /jobs/:id
Check the status of an async job created by GET /screenshot?async=true or POST /batch with async: true. The kind field is single or batch.
- Jobs are stored for about 1 hour after they are created, then return
404. - Only the account that created a job can read it; other accounts get
404. - Download links (
result.storagePath,batchResults[].downloadUrl) are signed again on every request. If one has expired, request the job again. - A job interrupted by a server restart ends as
failedwitherrorCode: "JOB_INTERRUPTED". Submit it again.
Job Statuses
Success
Failure
Batch job (in progress)
batchResults fills in as each URL finishes, so you can use partial results before the job is done.
GET /health
Returns service health — no auth required.
MCP Server
SnapshotFlow now exposes MCP directly from the backend at https://api.snapshotflow.com/mcp. This is the primary remote MCP endpoint for agents and MCP-compatible clients.
api.snapshotflow.com. Tool calls run on SnapshotFlow servers; nothing renders on your machine. Client setup guides: Claude Code, Cursor, Claude, Codex, VS Code, Antigravity, Zed. Overview on the MCP page.
Remote MCP endpoint
How it works
- The MCP transport is served by the backend itself.
- The MCP tools call the same screenshot engine and storage layer as the HTTP API.
- Available tools are
screenshot,batch_screenshot,visual_diff,extract_text, andcheck_job.
Available MCP tools
| Tool | Description |
|---|---|
| screenshot | Capture one URL or base64 HTML. Returns an image plus metadata, content, and cache info. |
| batch_screenshot | Capture up to 10 URLs in one request. Returns a signed download link per URL, plus the image unless include_images: false. Set async: true to get a job id right away and poll check_job. Blocks ads and cookie banners by default. |
| visual_diff | Compare two URLs visually and return a diff image with change statistics. Blocks ads and cookie banners by default. |
| extract_text | Return page content as Markdown, plain text, or HTML without an image. |
| check_job | Check an async job started by screenshot or batch_screenshot with async: true, or by the HTTP API. Batch jobs report progress and partial results. |
Coming Soon roadmap
Video capture — GET /video
Record a page interaction as an MP4 or WebM file. Supports scroll/click action replay, configurable duration and FPS, and the same response_type convention as /screenshot — stream the binary directly or get a storage path / async job_id.
Planned Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| url | string | — | Page to record required |
| duration | integer s | 5 | Recording duration in seconds (max 60) |
| fps | integer | 25 | Frames per second |
| format | enum | mp4 | mp4 or webm |
| width / height | integer | 1280 / 800 | Viewport dimensions |
| actions | JSON array | — | Scroll / click actions to replay during recording, e.g. [{"type":"scroll","y":800,"delay":1000}] |
response_type convention — stream the binary file or return a JSON with a storage path / async job_id.