Repository avatar
Communication
v0.1.2
active

api-screenshot

io.github.matbrons/api-screenshot

Clean full-page screenshots of real sites: cookie banners, pop-ups, chat widgets and ads removed.

Documentation

api-screenshot

CI

A screenshot API you run yourself. It takes full-page shots of real sites with the cookie banners, pop-ups, chat widgets and ads removed. It runs on your own Cloudflare account or on any server with Docker.

Examples and docs: apiscreenshot.com

Before: allbirds.com behind a country pop-up and a cookie consent box. After: the same page with both gone, as the API returns it.

curl -H "Authorization: Bearer $API_KEY" \
  "https://api-screenshot.your-subdomain.workers.dev/screenshot?url=https://www.theguardian.com&full_page=true" -o shot.png
  • Cookie banners, pop-ups, chat widgets and ads removed by default.
  • A captcha, bot check or error page comes back as an error that says so, never as a picture of it.
  • Safe to put on the internet: its own API key, a guard against requests to private addresses, and limits.
  • One API, on your Cloudflare account or on any server with Docker.

Contents: Run it (Cloudflare, your own server, safe by default) · Use it (JSON, signed URLs, caching, options, errors) · Use it from an AI agent · Settings · Ads, trackers and filter lists · Sites that block bots (retries) · Safety · Limits · Develop

Run it

On Cloudflare

Deploy to Cloudflare

The button copies this repo to your GitHub account and deploys it to your Cloudflare account. It asks for one secret, API_KEY: paste a long random string, for example from openssl rand -hex 32, and keep it. Your API is then at https://api-screenshot.<your-subdomain>.workers.dev.

Or from a clone:

npm install
npx wrangler deploy
API_KEY=$(openssl rand -hex 32); echo "Your API key: $API_KEY"
echo "$API_KEY" | npx wrangler secret put API_KEY

It uses Browser Rendering, which the free Workers plan includes with a daily limit (see Limits).

On your own server

API_KEY=$(openssl rand -hex 32); echo "Your API key: $API_KEY"
docker run -d --restart unless-stopped -p 3000:3000 -e API_KEY="$API_KEY" ghcr.io/matbrons/api-screenshot

The image runs on amd64 and arm64. It is published when a version is tagged, so it appears after the first release. To build it yourself instead: docker build -t api-screenshot .

Or without Docker, with Node 22.19 or newer and Chrome or Chromium installed:

npm install
API_KEY=$(openssl rand -hex 32); echo "Your API key: $API_KEY"
API_KEY="$API_KEY" HOST=127.0.0.1 npm start

It finds Chrome or Chromium on its own; set CHROME_PATH if it doesn't. HOST=127.0.0.1 keeps it to your own machine; leave it out on a server, where it listens on every address.

The server path uses a real Chromium, so it gets past more bot walls than the Worker does.

Safe by default

A screenshot API on a public URL lets anyone spend your browser time. So until API_KEY (or SIGNING_SECRET, for signed URLs) is set, every screenshot request is refused with not_configured, and so is a key shorter than 16 characters or one copied from an example. If you really want it open, for example on a private network, set ALLOW_PUBLIC_ACCESS=true.

Use it

# GET with query options
curl -H "Authorization: Bearer $API_KEY" \
  "http://localhost:3000/screenshot?url=https://example.com&full_page=true&format=jpeg" -o shot.jpg

# POST with a JSON body
curl -X POST http://localhost:3000/screenshot \
  -H "Authorization: Bearer $API_KEY" -H "content-type: application/json" \
  -d '{"url": "https://example.com", "viewport_width": 390, "viewport_mobile": true}' -o shot.png

The key can also go in an X-API-Key header. It is never taken from the URL, where it would end up in logs and browser history: a request with access_key in the query is refused. To put a shot in an <img> tag or a link, use a signed URL.

A shot comes back as the image (or PDF) itself, with these headers:

HeaderValue
x-final-urlThe URL after redirects
x-target-statusThe HTTP status the site answered with
x-removed-elementsHow many things were removed from the shot: the cookie banner, whether it was answered or hidden, plus each pop-up, backdrop, chat widget or ad that was showing. A banner and its own parts count as one. 0 when there was nothing to remove.
x-consent-managerThe consent tool behind the cookie banner that was removed (see below). Not sent when no banner was removed.
x-page-heightThe page's full height in CSS pixels
x-truncatedtrue when the shot was cut off: the page (or the selector element) was taller than full_page_max_height, or than 16384 device pixels (see Limits)
x-cacheHIT when the shot came from the cache, MISS when it was taken now and kept, BYPASS when the cache wasn't read (fresh, or caching off). See Caching.
ageOn a HIT: seconds since the shot was taken
x-overlay-remainingcookie_banner or popup when one is still on screen in the shot, after every attempt to remove it. Not sent when the shot is clean.

x-consent-manager is one of:

  • The tool's name, for the common ones: OneTrust, Cookiebot, Didomi, Usercentrics, Sourcepoint, TrustArc, Quantcast, consentmanager, CookieYes, Complianz, iubenda, Osano, Shopify and others.
  • For a site with a banner of its own, the name of autoconsent's rule for it, usually the site (airbnb).
  • generic: a banner recognised by its look and words, not by a known tool.

Before the shot, a last check looks for a cookie banner or pop-up that is still covering part of the screen. If it finds one, it presses Escape, then the banner's reject or close button (never accept), and cleans up again. One that survives all that is left in the shot and named in x-overlay-remaining, so you can retry or flag it. A site's own sticky header or menu doesn't count, even when it has a "Sign up" link.

JSON and page details

With response_type=json the answer is JSON instead of the file: the page's details plus the image or PDF in base64. response_type=metadata gives the details alone and skips the shot, which is quicker.

{
  "url": "https://example.com/",
  "final_url": "https://example.com/",
  "status": 200,
  "title": "Example Domain",
  "description": null,
  "icon": "https://example.com/favicon.ico",
  "open_graph": { "title": "...", "image": "https://..." },
  "page_height": 800,
  "removed_elements": 0,
  "consent_manager": null,
  "overlay_remaining": null,
  "truncated": false,
  "content_type": "image/png",
  "size": 18734,
  "image": "iVBORw0KGgo..."
}

open_graph holds the page's og: tags without the prefix. icon is the page's own icon link, or /favicon.ico when it has none (which may not exist).

Signed URLs

To put a shot straight into an <img> or og:image tag without giving away your key, sign the URL instead. Set a second secret, SIGNING_SECRET (16 characters or more, for example from openssl rand -hex 32; on Cloudflare echo "$SIGNING_SECRET" | npx wrangler secret put SIGNING_SECRET, or add it under the Worker's settings), then add a signature to each URL:

  1. Take every parameter, including expires if you want the link to stop working at some point (a Unix time in seconds).
  2. Sort them by name, percent-encode names and values (everything except A-Z a-z 0-9 - _ . ~) and join them as name=value&name=value.
  3. signature is the HMAC-SHA256 of that string with SIGNING_SECRET, in hex.

Anyone can read a signed URL, but changing, adding or removing any parameter breaks it. A wrong signature gets unauthorized with reason: signature_invalid, an expired one reason: signature_expired. Only GET requests can be signed. Make signed URLs on your server, never in the browser, so the secret stays with you.

In Node.js:

import { createHmac } from 'node:crypto';

const encode = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);

function signedUrl(base, options, secret) {
  const query = Object.keys(options).sort()
    .map((name) => `${encode(name)}=${encode(String(options[name]))}`)
    .join('&');
  const signature = createHmac('sha256', secret).update(query).digest('hex');
  return `${base}/screenshot?${query}&signature=${signature}`;
}

signedUrl('https://api-screenshot.your-subdomain.workers.dev', {
  url: 'https://example.com',
  full_page: true,
  expires: Math.floor(Date.now() / 1000) + 7 * 24 * 3600, // optional: valid for a week
}, process.env.SIGNING_SECRET);

In a shell, with the query already sorted and encoded:

QUERY='full_page=true&url=https%3A%2F%2Fexample.com'
SIG=$(printf '%s' "$QUERY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -r | cut -d' ' -f1)
echo "https://api-screenshot.your-subdomain.workers.dev/screenshot?$QUERY&signature=$SIG"

With only SIGNING_SECRET set and no API_KEY, the API takes signed URLs and nothing else.

Caching

A finished shot is kept for a day, so the same request again comes back at once and costs no browser time. Requests count as the same when their options are, after defaults are filled in: url=example.com and url=https://example.com/ share one shot. Only real shots are kept. A blocked, blank or any other error is never cached, so the next request tries again.

The cache is checked after the key or signature, so a cached shot never goes to someone who couldn't have asked for it. The x-cache header says whether a shot came from the cache. cache-control tells browsers how long they may keep it too: private for requests with the key, public for signed URLs (never past their expires), so a CDN in front can serve them.

On Cloudflare, shots are kept in Workers KV; the deploy creates the namespace for you. On a server they are kept in a folder, CACHE_DIR, up to CACHE_MAX_MB, and the shots used longest ago make room for new ones. In Docker that folder is /var/cache/api-screenshot; add -v api-screenshot-cache:/var/cache/api-screenshot to docker run to keep the shots when the container is replaced.

Options

Option names match the ones common to hosted screenshot APIs, so most requests written for one of those work here unchanged. An unknown option is refused, so a typo doesn't fail silently.

OptionDefaultWhat it does
urlrequiredThe page to shoot. https:// is added when missing.
htmlMarkup to render instead of a url, in a POST body, up to a million characters. Everything it loads still passes the address checks. Relative links have no base: use full URLs or a <base href>. Banner and pop-up removal are off for it unless you turn them on.
formatpngpng, jpeg, webp or pdf
image_quality801 to 100, for jpeg and webp
response_typeby_formatby_format: the file itself. json: details and the file in base64. metadata: details only, no shot. See JSON and page details.
full_pagefalseThe whole page instead of the first screen
full_page_max_height10000Cut the page off here, in CSS pixels
viewport_deviceA device's screen size, scale and user agent: iphone_se, iphone_13, iphone_13_pro_max, iphone_15, iphone_15_pro, iphone_15_pro_max, iphone_16, pixel_5, galaxy_s8, ipad, ipad_mini, ipad_pro_11, ipad_pro, galaxy_tab_s4, laptop or desktop. Add _landscape to turn it. The viewport_* options below still change single values.
viewport_width1280240 to 3840
viewport_height800240 to 2400
device_scale_factor10.5 to 3. Use 2 for sharp text on retina screens. viewport_width (or clip_width) times this can be at most 3840 device pixels: 1920 at 2, 1280 at 3. A tall shot is cut at 16384 device pixels: 8192 CSS pixels at 2.
viewport_mobilefalseMobile user agent and touch
wait_untilnetworkidle2load, domcontentloaded, networkidle0 or networkidle2
wait_for_selectorWait until this CSS selector is on the page
delay0Extra seconds to wait before the shot, up to 10
timeout30Seconds for the whole capture, up to MAX_TIMEOUT_SECONDS
selectorShoot only this element
clip_x, clip_y, clip_width, clip_heightShoot this part of the page, in CSS pixels from its top left. Width and height are needed; x and y start at 0. Can't be used with full_page or selector.
hide_selectorsCSS selectors to hide
clickCSS selectors to click, in order, before the shot, up to 10. One that matches nothing fails with selector_not_found.
stylesCSS added to the page
scriptsJavaScript run in the page before the shot, after clicks. It may use await. An error fails with script_error.
block_cookie_bannerstrueDismiss cookie banners, refusing consent where the site allows it
block_popupstrueRemove newsletter pop-ups, modals and sticky overlays
block_chatstrueRemove chat widgets and other corner widgets (the reCAPTCHA badge, push-notification prompts)
block_adstrueBlock ads: requests to ad networks, and the empty ad boxes left on the page. Uses EasyList.
block_trackerstrueBlock tracking scripts and pixels, using EasyPrivacy. Their banners and badges go with them.
block_requestsRequests not to load, up to 100. A host (ads.example.com) blocks it and its subdomains; a pattern with * matches the whole URL (*.example.com/track/*, *.mp4).
block_resourcesKinds of request not to load: image, media, font, stylesheet, script, xhr, fetch, websocket, document (frames; never the page itself), texttrack, eventsource, manifest, prefetch, ping, other and a few rarer ones
headersExtra request headers, one Name: value per line, or a JSON object. Sent only to the page's own site and its subdomains, never to the other sites it loads from. Host, Cookie, User-Agent and connection headers can't be set.
cookiesCookies set before the page loads, one per line: name=value; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Lax. Without Domain a cookie belongs to url.
user_agentThe user agent to send, in place of the browser's own
accept_languageLanguages in order, such as de-DE,de. Sets the Accept-Language header, navigator.language and how dates and numbers are written.
time_zoneA time zone such as Europe/Berlin
dark_modefalseAsk the page for its dark theme
reduced_motionfalseAsk the page to turn off animations
media_typescreen or print: the CSS media type. A PDF uses print unless set (or screen with pdf_fit_one_page).
omit_backgroundfalseTransparent background where the page has none (png, webp and pdf)
pdf_paper_formatletterletter, legal, tabloid, ledger or a0 to a6
pdf_landscapefalseTurn the paper sideways
pdf_print_backgroundtruePrint background colours and images
pdf_fit_one_pagefalseOne page as wide as the viewport and as tall as the page, instead of paper pages. Cut at full_page_max_height.
pdf_margin0Margin on every side, such as 20px, 1cm, 0.5in or 10mm. pdf_margin_top, pdf_margin_right, pdf_margin_bottom and pdf_margin_left set one side.
proxyServer only, and only when ALLOW_REQUEST_PROXY is on: your own proxy for this shot. See Sites that block bots.
retry10 to 2: more tries after a browser crash, a timeout or a blank page, and, with a list of proxies, after a blocked page or a failed proxy. All tries share timeout. See Retries.
fail_on_statusHTTP statuses that make the request fail with error_page instead of returning a shot, such as 404,500-599 or a JSON array
cache_ttl86400Seconds a cached shot may be reused, and how long a new one is kept, up to 2592000 (30 days). 0 takes a new shot and keeps nothing. The default is CACHE_TTL_SECONDS.
freshfalseTake a new shot even when one is cached, and keep it in place of the old one
cache_keyAny text, up to 200 characters, to keep a separate copy of the same shot
cachetruefalse is the same as cache_ttl=0
signature, expiresFor signed URLs

Lists (hide_selectors, click, block_requests, block_resources, headers, cookies) can be a JSON array, or in a query string the same option given more than once. hide_selectors, block_requests and block_resources also take one comma-separated value; click, headers and cookies, whose values may hold commas, take one per line (%0A in a URL). A signed URL can't repeat an option, so use the single-value form there.

Errors

Anything that isn't a shot is JSON: {"error": "blocked", "reason": "captcha", "message": "..."}.

errorStatusMeaning
invalid_options400The request is wrong. The message says which option.
unauthorized401The API key is missing or wrong, or a signed URL is wrong (reason: signature_invalid) or expired (reason: signature_expired)
url_not_allowed403A private, local or unsafe address, also after a redirect
blocked422A captcha, bot check or consent wall stood in front of the page. reason is captcha, bot_check, consent_wall, access_denied or rate_limited.
blank422The page rendered nothing
error_page422The site showed its own error. reason is http_404, http_503 and so on, or crashed. Also when the browser ended on its own error page; reason is then the browser's error code, such as ERR_TOO_MANY_REDIRECTS.
selector_not_found422selector, wait_for_selector or click matched nothing
script_error422Your scripts threw an error (the message has it) or didn't finish in time
unreachable502DNS, TLS or the connection failed, also on a redirect or a later navigation. reason is the browser's error code, such as ERR_NAME_NOT_RESOLVED.
proxy_not_allowed403proxy was sent, but this server doesn't take one from a request, or it points at a private address
proxy_error502Your proxy failed: wrong login, refused or didn't answer. The message says which.
busy503All browsers are in use. Try again shortly. On Cloudflare, if it goes on for minutes, today's browser time may be used up without Cloudflare saying so; the message says this too.
quota_exceeded429Cloudflare only: today's browser time is used up. It resets at 00:00 UTC. The Retry-After header gives the seconds until then.
browser_unavailable503No browser could be started
not_configured503No usable API_KEY or SIGNING_SECRET is set, or PROXY_URL or PROXY_URLS can't be used, so screenshots are off. The message says which.
timeout504The capture took longer than timeout

Use it from an AI agent

The API is also an MCP server at /mcp, so Claude, Cursor and other AI tools can take screenshots themselves. It takes the same API key and has two tools:

  • screenshot: the page as an image, with a short note next to it: the final URL, the HTTP status, the title, how many banners and pop-ups were removed, and whether the page was cut off.
  • page_details: the page's details as JSON, without an image, as with response_type=metadata.

A captcha, bot wall, error page or blank page comes back as a tool error with the same code and message as from /screenshot, never as an image.

Claude Code:

claude mcp add --transport http screenshot https://api-screenshot.your-subdomain.workers.dev/mcp \
  --header "Authorization: Bearer $API_KEY"

Cursor (~/.cursor/mcp.json) and other clients that take a URL and headers:

{
  "mcpServers": {
    "screenshot": {
      "url": "https://api-screenshot.your-subdomain.workers.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:API_SCREENSHOT_KEY}" }
    }
  }
}

Claude Desktop, through mcp-remote, in claude_desktop_config.json:

{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api-screenshot.your-subdomain.workers.dev/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your API key>" }
    }
  }
}

Any other client: MCP over Streamable HTTP at https://<your host>/mcp, with the key as Authorization: Bearer <key> or X-API-Key: <key>. The server keeps no sessions, so it runs the same on Cloudflare and on your own server.

To check it by hand, send a JSON-RPC request with both content types in Accept:

curl https://<your host>/mcp -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The tools return what AI clients can take: a JPEG of the first screen unless asked otherwise, one pixel per CSS pixel, a full page cut at 4,000 px (full_page_max_height goes up to 8,000), and at most 3 MB. A bigger shot is refused with a hint to make it smaller. Most clients scale a tall image down, so for small text a selector or a phone viewport_device reads better than a whole page.

For tools that read an API description instead, /openapi.json describes /screenshot in OpenAPI 3.1, with your server's limits filled in. It needs no key.

Settings

Environment variables on a server. On Cloudflare, API_KEY and SIGNING_SECRET are secrets and the rest are vars in wrangler.jsonc:

VariableDefault
API_KEYnoneEvery request must carry it. 16 characters or more. Without it, screenshots are refused.
SIGNING_SECRETnoneTurns on signed URLs. 16 characters or more. Use a different one from API_KEY.
ALLOW_PUBLIC_ACCESSfalsetrue serves screenshots without a key, to anyone who can reach the URL
MAX_TIMEOUT_SECONDS60The longest timeout a request may ask for
MAX_FULL_PAGE_HEIGHT20000The tallest full-page shot a request may ask for
BROWSER_KEEP_ALIVE_SECONDS0Cloudflare only: 0 closes the browser after each shot. 60 to 600 keeps it open that long for the next shot, which is faster but spends browser time while idle.
MAX_CONCURRENCY2Server only: shots taken at the same time
PORT, HOST3000, 0.0.0.0Server only
CHROME_PATHfound automaticallyServer only
CHROME_NO_SANDBOXServer only: 1 runs Chromium without its own sandbox. The Docker image sets it and runs as an unprivileged user instead.
PROXY_URLnoneServer only: send all browser traffic through your own proxy, such as http://user:pass@proxy.example.com:8080 or socks5://user:pass@proxy.example.com:1080
PROXY_URLSnoneServer only: a list of your own proxies, separated by commas, spaces or new lines. Shots take them in turn; a retry goes through the next one. May be set together with PROXY_URL.
ALLOW_REQUEST_PROXYfalseServer only: true lets a request bring its own proxy. Needs API_KEY.
CACHE_TTL_SECONDS86400How long a shot is kept and reused when a request doesn't set cache_ttl. 0 turns the cache off.
CACHE_DIRapi-screenshot-cache in the temp folder; /var/cache/api-screenshot in DockerServer only: where shots are kept
CACHE_MAX_MB1024Server only: the most the cache folder may hold. 0 turns the cache off.
DESKTOP_CHROMEtrueServer only: the browser reads as a desktop Chrome (user agent, no automation flag, desktop screen). false lets it show as headless Chromium. See Sites that block bots.
BROWSER_LANGUAGEen-USServer only: the browser's language, sent to sites in Accept-Language
BROWSER_TIMEZONEAmerica/New_YorkServer only: the browser's time zone, such as Europe/Amsterdam
FETCH_BLOCKLISTStrueServer only: false skips the filter lists and uses the small built-in list (see Ads, trackers and filter lists)

Ads, trackers and filter lists

Ads, trackers and cookie banners are blocked with the public filter lists that ad blockers use:

From these lists it uses the rules that block a whole host (such as an ad network) and the CSS rules that hide elements. Rules for single URL paths or request types, and rules that run scripts in the page, are left out.

The lists are not part of this repo. They are fetched from their own sites:

  • On Cloudflare, each time the Worker is built and deployed. Deploy again to get newer lists.
  • On a server, when it starts and once a day after that. Set FETCH_BLOCKLISTS=false to turn this off.

If a list can't be fetched, the others are still used, and a small built-in list of the biggest ad and tracker hosts is always there. The lists keep their own licences (see Credits). They are read with Ghostery's adblocker parser (MPL-2.0) at build or start time only; the Worker itself doesn't include it.

Sites that block bots

Some sites block automated browsers. You get a blocked error for those, with a reason, never a shot of the captcha. This project doesn't solve captchas, and beyond a few settings that make a headless Chrome look like a desktop one (below), it doesn't fake what the browser is.

What helps:

  • Run it on your own server. The Docker version runs a real Chromium set up to read as a desktop Chrome (see below), so it gets past more bot walls.
  • Use your own proxy. Set PROXY_URL to an http://, https:// or socks5:// proxy, with user:pass@ if it needs a login. Every shot then goes out through it. The login never shows up in logs or error messages.
  • Or a list of them. Set PROXY_URLS to several proxies, separated by commas, spaces or new lines (percent-encode a comma or space inside a login). Each shot takes the next one in turn, and a blocked page is tried again through another. See Retries.
  • Or one per request. With ALLOW_REQUEST_PROXY=true and an API_KEY, a request may send proxy itself. Send it in a POST body, so the login stays out of URLs and access logs. A proxy from a request must be on the public internet, and it is used alone, never mixed with your list.

The safety checks still apply through every proxy: your server looks up each site's address first and refuses private ones, then asks the proxy for that exact address. So the proxy never looks up a name itself, and a name that points into the proxy's own network is refused. A retry goes through the same checks.

A desktop Chrome, nothing more

On a server the browser runs as a real Chromium in Chrome's new headless mode, and changes a few things so it reads as a desktop Chrome rather than an automated one:

  • the user agent and its client hints say Chrome, not "HeadlessChrome";
  • navigator.webdriver is false, and Chromium's automation flag is off;
  • the screen is 1920 × 1080, where headless reports 800 × 600;
  • the language and time zone are the ones you set with BROWSER_LANGUAGE and BROWSER_TIMEZONE. Set them to match where your proxies are.

DESKTOP_CHROME=false drops the user agent change and the flags, and shows the browser as headless Chromium.

That is all it does. It doesn't fake hardware, canvas, WebGL, fonts or plugins, and it doesn't solve captchas. In a test of 30 popular sites from a data-centre address it took 23 clean shots where plain headless Chromium took 20 (El País, Zalando and CNN came through). The other 7 still blocked it: Forbes, Medium, Reddit, G2, IKEA, Zillow and bol.com. Those seem to judge the address as much as the browser; a proxy on a home or mobile address may get you past some of them.

On Cloudflare the user agent is set the same way, but it makes little difference: Cloudflare's browser adds signed headers that tell sites it is a bot, whatever the user agent says, and its traffic comes from Cloudflare's addresses.

Retries

retry (default 1, up to 2) tries a shot again when a second try has a fair chance:

  • after a browser crash, a timeout or a blank page;
  • with a list of proxies, after a blocked page, a failed proxy, or a site that couldn't be reached through it. The retry goes through a proxy not yet tried for this shot. Without another proxy, a blocked page is reported as it is: the same address would get the same answer.

All tries share the request's timeout, and a retry only starts with at least 8 seconds of it left. A failure after retries says what happened on each try. A shot that came through on a retry is cached like any other; a request that ends blocked or failed is not cached, and a cached shot is served without any new try.

A proxy that fails (refuses the connection, can't be reached, or rejects the login) is skipped for 30 seconds, then for twice as long each time it fails again, up to 10 minutes. A blocked page doesn't count against a proxy: its address may still be fine for other sites. If every proxy is resting, the one due back first is tried.

fail_on_status turns a page with a status you list into an error_page error instead of a shot, for example 404,500-599. It is never retried.

On Cloudflare

A proxy only works on a server. Cloudflare's browser can't send its traffic through one. If PROXY_URL or PROXY_URLS is set on Cloudflare, every screenshot is refused with not_configured, rather than going out without the proxy. A proxy in a request gets proxy_not_allowed. retry still works there for crashes, timeouts and blank pages, but a retry goes out from the same Cloudflare addresses.

Safety

A screenshot API loads any URL it is given, so it would otherwise let anyone reach your private network. This one refuses local, private and cloud-metadata addresses. It checks the first URL, every redirect and every request the page makes, and refuses when in doubt.

  • On a server, all browser traffic goes through a small built-in proxy. The proxy resolves each host itself and connects only to the public address it checked. That also covers WebSockets and DNS tricks that point a public name at 127.0.0.1. With your own proxy set, these checks stay on your server and the proxy is only asked for addresses that passed them.

  • On Cloudflare, the browser runs in Cloudflare's network, not yours, so there is little private network to reach. Every request the browser makes (the page itself, each redirect, frame, image and script) is held until its host passes the check, by name and by a DNS lookup over HTTPS. Two gaps remain, and Browser Rendering offers no way to close them:

    • The browser looks the name up again itself, so a name that changes its answer between the two lookups (DNS rebinding) can get past the check. The Worker can't make the browser connect to the address it checked.
    • WebSocket connections from the page are not seen by the check at all.

    Cloudflare doesn't document whether its browser network can reach private addresses. If you need every connection checked, run it on a server.

Each shot runs in a fresh incognito context: no cookies or storage carry over between requests.

scripts, html, headers and cookies don't open a way around this. Any page can already run its own scripts, and these run in the same page under the same checks: every request they cause, to any address, passes the guard like the page's own. A header can't change where a request goes (Host and connection headers are refused), and extra headers and cookies only reach the site you asked for. The API key or signature is checked before any option is read, and every option is part of the cache key, so two requests that differ in any way never share a shot. /mcp takes the API key too (not a signed URL), and every tool call goes through the same checks as /screenshot.

Limits

  • Bot walls. Some sites block every headless browser (in a test of 30 popular sites: Forbes, Medium, Reddit, G2, IKEA, Zillow and bol.com). You get a blocked error for those, not a shot. The server path gets through more often than the Worker, and a proxy can help. See Sites that block bots.
  • Cloudflare's free plan gives 10 minutes of browser time a day, reset at 00:00 UTC. A shot usually takes 5 to 15 seconds of it, so that is roughly 40 to 120 shots a day. After that you get quota_exceeded until the next day. Cloudflare answers both a used-up day and a short wait for a free browser with a 429, sometimes with the same "Rate limit exceeded" text; the API tells them apart by Cloudflare's Retry-After, which runs to 00:00 UTC only for a used-up day. Shots served from the cache don't count, and Workers KV's free plan allows 1,000 new shots kept and 100,000 served from it a day. It also allows 3 browsers at once and 1 new browser every 20 seconds, so requests that arrive together wait their turn (up to about 20 seconds) or get busy. Each browser is closed right after its shot, so no time is spent idle.
  • Cloudflare's paid plan ($5 a month for Workers) includes 10 browser hours a month, then $0.09 an hour, with no daily cap. With steady traffic, set BROWSER_KEEP_ALIVE_SECONDS=60 so shots reuse a warm browser.
  • Lazy images are loaded before a full-page shot. The page is scrolled down a screen at a time, each step waiting for what came into view, and then every image in the shot is waited for. A page that is still fetching when timeout runs out can miss an image near the bottom; a longer timeout helps.
  • Very long pages are cut at full_page_max_height, and the x-truncated header says so. Chromium can't draw an image taller than 16384 device pixels (it starts repeating the page), so a shot is also cut there: 16384 CSS pixels at device_scale_factor 1, 8192 at 2, 5461 at 3.
  • Very wide shots. viewport_width (or clip_width) times device_scale_factor can be at most 3840 device pixels, a 4K screen. Above that you get invalid_options, so no single shot needs much more than 250 MB of memory to draw. A page wider than its viewport can still give a full-page or selector shot a little wider than this.
  • Cookie banners are dismissed with the rules from DuckDuckGo's autoconsent, over 1,600 rules for the common consent tools and for single sites. A banner it doesn't know is hidden with the EasyList Cookie List, or by a fallback that looks for fixed overlays. A banner that survives is named in x-overlay-remaining. A small one can still slip through now and then.
  • Ads are blocked by host and hidden by CSS, as above. An ad served from the site's own domain, or one built into the page in a way the lists don't name, can still show.

Develop

npm test               # unit tests, plus browser tests when Chrome is installed
npm run typecheck
npm run build:worker   # bundles the Worker without deploying it
npm run live-test      # 30 real sites; writes shots and a report to your temp folder

To check a running install from the outside (up, closed without the key, a real PNG back):

APISHOT_TEST_URL=https://api-screenshot.your-subdomain.workers.dev APISHOT_TEST_KEY=your-key ops/watch.sh

To shoot real sites through a running install (five by default, --all for the whole list in ops/live-sites.txt):

APISHOT_TEST_URL=http://localhost:3000 APISHOT_TEST_KEY=your-key ops/smoke-sites.sh --all ./shots

CI runs the tests on Node 22 and 24, builds the Worker, then builds the Docker image, checks that it refuses requests without a key, and shoots five real sites through it. Run the CI workflow by hand with sites: all to put the whole list through the Docker image.

Credits

Cookie banners are handled with autoconsent by DuckDuckGo (MPL-2.0). Filter lists are read with Ghostery's adblocker (MPL-2.0). The lists come from EasyList (EasyList and EasyPrivacy: GPL 3 or CC BY-SA 3.0, at your choice; the Cookie List: CC BY 3.0), fetched when you build or start. All of them, with their licences, are in THIRD_PARTY_NOTICES.md.

Licence

MIT

OCI
ghcr.io/matbrons/api-screenshot:0.1.2
Install Command
docker pull ghcr.io/matbrons/api-screenshot:0.1.2:undefined

Remote

streamable-http
https://{host}/mcp