Cookie Banner Screenshot API: Capture Clean Pages Without Consent Popups

Why This Is Timely

Consent interfaces are still an active web automation problem. The European Data Protection Board's cookie banner taskforce report remains a reference point for banner design and consent-pattern issues, and 2026 academic work continues to study how consent banners affect privacy choices and automation reliability. One recent paper, When the Abyss Looks Back, describes UMBRA, a system that combines text analysis, visual heuristics, interaction tracing, and cookie-state monitoring to detect evolving consent-banner dark patterns.

For teams using screenshots in scheduled monitors, sales reports, competitive audits, product thumbnails, and AI workflows, the practical task is narrower than consent-law analysis: capture the page state your application cares about, without a modal hiding the hero, price table, or checkout step.

What SnapshotFlow Does

The SnapshotFlow GET /screenshot endpoint exposes three layers for cleaner captures:

This is a single-page capture feature, not a batch-only feature. Use it on /screenshot when you need the full option set; the batch endpoint intentionally exposes a smaller shared option set.

Step 1: Capture a Clean Screenshot with cURL

Start with the generic blockers. Use -G and --data-urlencode so URLs and selector lists stay readable.

curl -G "https://api.snapshotflow.com/screenshot" \
  -H "X-Api-Key: $SNAPSHOTFLOW_API_KEY" \
  --data-urlencode "url=https://example.com/pricing" \
  --data "width=1440" \
  --data "height=900" \
  --data "full_page=true" \
  --data "block_cookie_banners=true" \
  --data "block_ads=true" \
  --data "block_trackers=true" \
  --output clean-pricing.png

Expected behavior: SnapshotFlow launches a Chromium page, applies the blocking options before navigation and capture, then returns the image bytes. If the page was captured successfully, the file is written to clean-pricing.png. If the URL is invalid, private, or unreachable, the API returns a structured error instead of an image.

Step 2: Add Selector Fallbacks for Custom Overlays

Cookie-banner lists can miss custom consent flows or site-specific promotion modals. When you know the selector, hide it explicitly:

curl -G "https://api.snapshotflow.com/screenshot" \
  -H "X-Api-Key: $SNAPSHOTFLOW_API_KEY" \
  --data-urlencode "url=https://example.com/pricing" \
  --data "block_cookie_banners=true" \
  --data-urlencode "hide_selectors=.cookie-banner,.consent-modal,.intercom-launcher" \
  --data "wait_until=networkidle2" \
  --data "delay=500" \
  --output clean-with-fallbacks.png

hide_selectors adds CSS that sets the matched elements to display:none before the screenshot. Pair it with a small delay when an overlay is injected after the initial page load.

Step 3: Use the Node.js SDK in a Monitoring Job

The official SnapshotFlow Node.js SDK exposes the same options in camelCase. The SDK serializes arrays and converts option names to the API's snake_case parameters.

import { SnapshotFlow } from "snapshotflow";

const client = new SnapshotFlow({
  apiKey: process.env.SNAPSHOTFLOW_API_KEY!,
  baseUrl: "https://api.snapshotflow.com",
});

const shot = await client.take({
  url: "https://example.com/pricing",
  width: 1440,
  height: 900,
  fullPage: true,
  blockCookieBanners: true,
  blockAds: true,
  blockTrackers: true,
  hideSelectors: [".cookie-banner", ".consent-modal", ".chat-widget"],
  waitUntil: "networkidle2",
  delay: 500,
});

await shot.save("pricing-clean.png");

In a scheduled workflow, keep the target URL, viewport, blocking flags, selector fallbacks, and capture time beside the output file. That record helps explain why a future screenshot changed.

Step 4: Validate with a Control Capture

Before turning the setting on for a monitor, save two captures: one unblocked and one clean. Check that the clean version still shows the content you care about and does not hide first-party UI you need to audit.

When You Should Not Block the Banner

A clean screenshot is not always the right screenshot. Keep an unmodified capture when the banner itself is the subject of the workflow:

• Consent compliance review or legal evidence.
• UX review of the first-visit experience.
• Regression testing for the consent manager itself.
• Regional checks where the banner content must be visible.

For those jobs, take both versions: a default capture for evidence and a clean capture for downstream analysis.

Operational Advice

• Pin the viewport. Cookie banners often switch layout between mobile and desktop; keep width, height, and viewport_mobile explicit.
• Record fallback selectors. Treat selector rules as page-specific configuration, not hidden magic in a script.
• Use cache=false for audits. Cached images are useful for repeated previews, but a monitoring run usually wants a fresh page state.
• Prefer server-side API calls. Keep the API key in the X-Api-Key header from your backend, not in a public browser URL.
• Chunk large URL sets deliberately. If you need clean captures across many pages, reuse this single-page configuration in controlled queues. Use batch screenshots only when its smaller shared option set is enough.

FAQ

Sources

• European Data Protection Board: report of the cookie banner taskforce.
• When the Abyss Looks Back: evolving dark patterns in cookie consent banners.
• Ghostery adblocker project, the upstream blocker family used for common ad, tracking, and cookie-list blocking workflows.