How to block ads and cookie banners in Browserless screenshots

For Browserless’s REST screenshot API, add blockAds=true to enable its built-in ad blocker and blockConsentModals=true to handle cookie or GDPR banners. If a banner remains, use a site-specific consent selector or inject CSS to hide the known element before capture. Check the resulting image: blocking can affect page behavior, and a hidden overlay can leave a gap or conceal content.

1. Use Browserless’s REST screenshot endpoint

Send the two controls as query parameters on the /screenshot endpoint. Put the target URL and screenshot options in the JSON request body:

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&blockAds=true&blockConsentModals=true" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","options":{"type":"png","fullPage":true}}' \
  --output screenshot.png

Replace the placeholder token with your Browserless API token. Keep real tokens out of source code and published examples. The request asks for a full-page PNG; change type or fullPage in the body to suit the capture you need.

The controls have separate jobs:

• blockAds=true turns on Browserless’s built-in ad blocker, which Browserless says is powered by uBlock Origin.
• blockConsentModals=true enables handling for common cookie and GDPR consent banners.

Browserless documents these controls for its /screenshot and /pdf REST APIs, as well as BrowserQL sessions. See the REST launch parameters and BrowserQL launch parameters.

2. Handle a banner the built-in consent blocker misses

Browserless’s consent handling covers common platforms, including OneTrust and CookieBot. For an unsupported or customized banner, use a selector known to match the target site. The Browserless example shows checking and clicking a selector; examples include [id*=accept], [class*=accept], and button[id*=cookie].

These broad selectors are starting points, not universal rules. A match could be the wrong button, such as a reject or preferences control. Prefer a site-specific selector and check that the element is visible before clicking it. The Browserless consent example shows the consent-action pattern.

If the only requirement is to remove a known overlay from the rendered image, Browserless’s BAP page setup supports adding CSS before capture:

await page.addStyleTag({ content: ".cookie-banner { display: none !important; }" });

Replace .cookie-banner with a selector verified on the page. Inject this style before the screenshot call. Hiding an element changes the rendered view; it does not record a consent choice with the website. See Browserless cookies and page setup.

3. Choose ad-blocking rules when supported

When blockAds=true, Browserless also documents blockAdsInclude for selecting uBlock Origin Lite rulesets instead of loading all rulesets. Its recommended general-purpose list is:

ublock-filters,easylist,easyprivacy,pgl,ublock-badware,urlhaus-full

Use the parameter only on endpoints that honor it. Browserless lists BrowserQL endpoints, CDP WebSocket, and the /unblock, /screenshot, and /pdf REST endpoints. Some session and bundled-build cases continue to load the full set. A selected list may not provide identical coverage to the full set. Refer to the endpoint scope in the launch parameter documentation and BaaS launch options.

4. Configure BrowserQL sessions

For BrowserQL, Browserless documents blockConsentModals in session settings or launch JSON. A launch payload can enable the consent behavior for the session; when a site needs a specific action, use an explicit consent action with its known selector. The exact mutation and payload depend on the BrowserQL operation, so follow the current BrowserQL launch parameter reference and consent example.

The same practical division applies: use the built-in consent handling for common banners, and page-specific selector logic when a custom banner remains. For ads, check that the ad-blocking options are supported by the endpoint you are using.

5. Verify the captured page

1. Capture once with the controls enabled.
2. Inspect the image for remaining overlays, missing page content, large blank areas, or content unexpectedly covered by a selector.
3. If useful content is missing, compare with a capture that has blockAds disabled. Browserless warns that its ad blocker may cause some sites not to load correctly.
4. If your endpoint supports blockAdsInclude, try the documented ruleset selection and inspect the result again.
5. For a custom banner, verify the selector against the actual page and make sure a click targets the intended consent action.

These checks matter because removing an overlay can change the visible layout, and ad-blocking rules can affect resources a page needs.

6. Troubleshooting

Symptom	Likely cause	What to try
Cookie banner still appears	The banner is not covered by the built-in consent handling, or it uses a custom implementation.	Use a site-specific selector to check and accept the banner, or inject CSS to hide the known element if you only need it absent from the image.
The wrong consent control was clicked	A broad selector matched a reject, settings, or unrelated button.	Replace it with a selector specific to the intended control and check visibility before clicking.
Page content is missing or does not load correctly	Browserless cautions that its ad blocker can cause some sites to fail to load correctly.	Compare a capture with blockAds disabled. If supported, try blockAdsInclude with the documented rulesets and inspect again.
A blank strip remains after hiding a banner	The overlay may be hidden while spacing or a related page element remains.	Inspect the page’s layout and target the correct banner element. Avoid broad CSS rules that hide surrounding content.
blockAdsInclude has no apparent effect	The endpoint or session type may not honor that option.	Check the endpoint scope in Browserless’s launch parameter documentation; some session and bundled-build cases load the full ruleset.
The API request fails before producing an image	The token, endpoint, request body, or JSON formatting may be incorrect.	Confirm the API token, use the correct Browserless endpoint, send JSON with the content type shown above, and ensure the body contains a valid target URL.

7. Performance, reliability, and cost considerations

Browserless’s documented ad-blocking controls do not provide a performance guarantee. Blocking ads and trackers can change which resources a page loads, while the provider explicitly warns that some pages may not load correctly with ad blocking enabled. Treat the output as page-dependent and inspect captures that feed reports, previews, or other workflows where missing content matters.

Consent handling is also page-dependent: common platforms are covered, but custom implementations may need selectors or CSS. A selector can become stale when a site changes its markup, so keep site-specific rules easy to review and update.

This setup changes the Browserless capture behavior; it does not itself define your Browserless plan or request charges. Check your account’s current pricing and usage terms for cost details. Browserless does not publish a performance statistic in the cited documentation that would support a general speed claim for these options.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It can return a screenshot or PDF from one GET request. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot, and each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; the response identifies the page verdict and billing status in headers.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

See the ScreenshotNeo API documentation for request options. Python and Node.js clients can make the same GET request using their standard HTTP libraries. ScreenshotNeo also provides MCP tools so AI agents can take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

9. FAQ

Does hiding a banner mean the visitor consented?

No. Injected CSS only changes what is rendered in the capture. Use a consent action if the workflow needs to record a choice.

Can I use the controls for PDFs too?

Browserless documents the consent and ad controls for its /pdf REST API as well as screenshots. Confirm that any optional ruleset parameter is supported by your endpoint.

Should I always enable ad blocking?

Only if it suits the capture. Compare output when content is missing, since Browserless warns that ad blocking can affect some sites.