Blocking & Filtering

Cookie consent banners, chat widgets, ad overlays, newsletter popups — these elements appear on nearly every website and clutter your screenshots with content you don't need. The API provides built-in toggles to remove the most common distractions automatically, without you having to know the exact CSS selectors.

Block cookie banners

Almost every website shows a cookie consent banner on first visit. Since screenshots always look like a first visit (fresh browser session), you'll see these banners in every capture unless you block them.

Parameter	Type	Default	Description
`block_cookies`	boolean	`true`	Block cookie consent banners. Enabled by default.

This parameter is enabled by default because cookie banners appear in the vast majority of screenshots and are rarely the content you want to capture. The API blocks consent scripts (OneTrust, CookieBot, Osano, and others), hides common banner elements, and attempts to click "Accept" buttons.

When to disable it

Set block_cookies=false if you specifically need to see the consent banner — for example, when testing cookie compliance or auditing consent flows.

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "block_cookies": false
  }'

Block ads

Ads add visual noise to screenshots and slow down page loading. The block_ads parameter blocks advertising scripts and network requests before the page loads, and removes ad containers from the page.

Parameter	Type	Default	Description
`block_ads`	boolean	`false`	Block ads and trackers before capturing.

Example: News article without ads

News sites are often heavily ad-supported. Blocking ads gives you a clean capture of just the article content.

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news-site.com/article/123",
    "block_ads": true,
    "full_page": true
  }'

Block chat widgets

Chat widgets from Intercom, Crisp, Tawk.to, Drift, LiveChat, Zendesk, HubSpot, and similar services add floating buttons and popover windows, usually in the bottom-right corner. They obstruct content and add visual clutter to screenshots.

Parameter	Type	Default	Description
`block_chats`	boolean	`false`	Block chat widgets before capturing.

Example: Capture without chat widget

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "block_chats": true
  }'

Maximum cleanup

For the cleanest possible screenshot, enable all three blocking parameters. This is especially useful for thumbnails, archival captures, and automated monitoring where distractions reduce the quality of results.

const response = await fetch('https://api.screenshotrun.com/v1/screenshots', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    block_cookies: true,
    block_ads: true,
    block_chats: true,
    full_page: true,
    format: 'webp',
  }),
});

const { data } = await response.json();
console.log(data.links.image);

import requests

response = requests.post(
    "https://api.screenshotrun.com/v1/screenshots",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "block_cookies": True,
        "block_ads": True,
        "block_chats": True,
        "full_page": True,
        "format": "webp",
    },
)

data = response.json()["data"]
print(data["links"]["image"])

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.screenshotrun.com/v1/screenshots', [
        'url' => 'https://example.com',
        'block_cookies' => true,
        'block_ads' => true,
        'block_chats' => true,
        'full_page' => true,
        'format' => 'webp',
    ]);

$data = $response->json('data');

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "block_cookies": true,
    "block_ads": true,
    "block_chats": true,
    "full_page": true,
    "format": "webp"
  }'

require "net/http"
require "json"

uri = URI("https://api.screenshotrun.com/v1/screenshots")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  url: "https://example.com",
  block_cookies: true,
  block_ads: true,
  block_chats: true,
  full_page: true,
  format: "webp",
}.to_json

response = http.request(request)
data = JSON.parse(response.body)["data"]

body, _ := json.Marshal(map[string]any{
        "url": "https://example.com",
        "block_cookies": true,
        "block_ads": true,
        "block_chats": true,
        "full_page": true,
        "format": "webp",
    })

req, _ := http.NewRequest("POST",
    "https://api.screenshotrun.com/v1/screenshots",
    bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

var client = HttpClient.newHttpClient();

var body = """
    {
        "url": "https://example.com",
        "block_cookies": true,
        "block_ads": true,
        "block_chats": true,
        "full_page": true,
        "format": "webp"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.screenshotrun.com/v1/screenshots"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Performance benefit

Blocking ads and trackers isn't just about clean screenshots — it also speeds up page loading. Ad networks inject dozens of scripts and make hundreds of network requests. Blocking them means fewer resources to download, faster rendering, and faster screenshot delivery.

When built-in blocking isn't enough

The blocking parameters handle the most common third-party scripts and elements. But some sites use custom-built popups, modals, or overlays that don't rely on standard third-party scripts. For those, you have two additional options:

hide_selectors — hide specific elements by their CSS selector. See Element Screenshot for details.
css injection — write custom CSS to hide or restyle any element. See CSS & JS Injection.

Example: Combine blocking with manual hiding

Use built-in blocking for standard elements and hide_selectors for custom ones.

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "block_ads": true,
    "block_chats": true,
    "hide_selectors": [".custom-popup", ".exit-intent-modal", ".sticky-cta"]
  }'