How to Handle DataDome in Browser Automation

When DataDome challenges or blocks browser automation, treat that response as the website’s bot-protection decision. Don’t try to defeat it with fingerprint changes, proxy rotation, or challenge workarounds. If you have permission to automate the site, use an approved integration, contact its owner, or request bot authentication where applicable. If you own the site, inspect your DataDome integration and decision data to find out which traffic is being evaluated.

This guide covers authorized automation with Playwright, how commercial bots can request recognition, and what site owners should check. A challenge is not proof of which particular signal caused the decision: DataDome documents multiple detection layers, and only the site owner can inspect its own decision data.

Why DataDome may challenge browser automation

DataDome documents signature-based, behavioral, and reputational detection. Its examples include headless browsers and automation involving Selenium, Puppeteer, or Playwright. The models are updated over time, so a particular browser attribute or framework behavior is not a dependable way to predict whether a visit will be allowed.

DataDome’s Device Check documentation describes a client-side verification that can allow a request, block it, or request a CAPTCHA when more information is needed. A successful check in one situation does not guarantee that a particular automated browser will be admitted in another.

The JavaScript Tag is part of a broader detection setup. DataDome says it adds browser-side information, including behavior and device characteristics. Its documentation says the tag needs permission to read and write the datadome cookie and warns against changing that cookie’s attributes. Site owners implementing the tag should check the current supported-browser list in the official documentation.

An older article by DataDome VP of Research Antoine Vastel describes a Selenium Chrome fingerprinting technique. It was last updated on November 22, 2022, and cautions that navigator.webdriver alone is insufficient, that the example may not cover other frameworks, and that the cited fingerprint can be altered. Treat it as a historical illustration of one detection technique, not as a current access guide.

Choose the right path for your role

Your role	What to do	What to avoid
Automation operator with permission	Use the site’s approved integration or ask its owner what access and authentication it supports.	Assuming a browser setting or a successful Device Check guarantees access.
Commercial bot or AI agent operator	Follow DataDome’s bot authentication process: use a dedicated user agent, set up an authentication mechanism, and submit a request.	Assuming that submitting a request guarantees approval.
Website owner	Inspect your DataDome decision data and verify that the server-side and client-side integration matches your intended policy.	Inferring the exact reason for a block from the browser symptom alone.

Run authorized Playwright automation safely

The example below visits a site you are authorized to automate, records basic navigation information, and stops if the page appears to present a challenge. It does not attempt to solve or evade a challenge. Challenge pages vary, so the marker check is deliberately only a diagnostic hint; it is not a reliable way to identify every DataDome decision.

1. Install Playwright

python -m pip install playwright
python -m playwright install chromium

2. Save and run the script

Save this as authorized_visit.py. Set TARGET_URL to a URL you are permitted to access. If a challenge appears, preserve the captured diagnostic details and contact the site owner or use its approved access process.

import asyncio
import os
from playwright.async_api import async_playwright, TimeoutError as PlaywrightTimeoutError

TARGET_URL = os.environ.get("TARGET_URL", "https://example.com")
NAVIGATION_TIMEOUT_MS = 30_000

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        page = await browser.new_page()
        response = None
        try:
            response = await page.goto(
                TARGET_URL,
                wait_until="domcontentloaded",
                timeout=NAVIGATION_TIMEOUT_MS,
            )
        except PlaywrightTimeoutError:
            print("Navigation timed out; stop and check the site and network.")

        status = response.status if response else None
        title = await page.title()
        final_url = page.url
        # A heuristic for triage only; challenge pages and wording can vary.
        page_text = (await page.locator("body").inner_text(timeout=5_000)
                     if await page.locator("body").count() else "")
        challenge_hint = any(term in (title + " " + page_text).lower()
                             for term in ("datadome", "captcha", "verify you are human"))

        print({"status": status, "title": title, "final_url": final_url,
               "challenge_hint": challenge_hint})
        if challenge_hint or (status is not None and status >= 400):
            print("Automation stopped. Request authorized access from the site owner.")
        else:
            print("Page loaded without the diagnostic challenge hint.")

        await browser.close()

if __name__ == "__main__":
    asyncio.run(main())

Run it with TARGET_URL set in your shell, for example TARGET_URL=https://example.com python authorized_visit.py. Replace the example domain only with a site where you have authorization. The script reports an observed response status when the browser returns one; it does not establish why a decision was made.

Equivalent request-level diagnostics

A direct HTTP request can help an authorized operator inspect the response without running a browser. It does not reproduce browser behavior, and a response difference is not proof of the specific detection signal.

curl -i --max-time 30 https://example.com/

Node.js version using the built-in fetch API:

const url = process.env.TARGET_URL || 'https://example.com';
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 30_000);
try {
  const response = await fetch(url, { signal: controller.signal, redirect: 'manual' });
  console.log({ status: response.status, location: response.headers.get('location') });
  const body = await response.text();
  console.log(body.slice(0, 1000));
} catch (error) {
  console.error('Request failed or timed out:', error.message);
} finally {
  clearTimeout(timer);
}

Or skip the browser setup

If you are authorized to capture the target page, ScreenshotNeo can return a screenshot or PDF from one API request. It does not override a site’s access decision or bypass DataDome; use it only for pages you are allowed to capture. See the ScreenshotNeo API documentation.

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

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents the take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

For commercial bots: request authentication

DataDome’s documented route for commercial bots seeking recognition is to use a dedicated user agent, configure an authentication mechanism, and submit a request through its Bot Authentication process. The documented mechanisms include Web Bot Auth signatures, reverse DNS, static IP addresses, dynamic IP lists, and private AS checks. Which option is appropriate depends on the bot and the site’s policy. The site owner decides whether to authorize it, so a request is not a guarantee of access.

DataDome states that automated requests from an unauthenticated bot or AI agent are categorized as threat detection and blocked by default. If your use is legitimate, begin the authentication request before relying on automated access. Do not treat a challenge as an invitation to imitate a human visitor.

For site owners: diagnose the integration

Check the decision record. Use the decision data available to your DataDome account to identify what the integration observed. A browser-visible challenge alone does not reveal which layer or signal caused it.
Review both sides of the setup. Confirm that the server-side protection and any client-side JavaScript Tag are installed as intended. Check current documentation for supported browser versions and cookie requirements.
Confirm the request context. The Protection API expects backend infrastructure to submit request metadata and receive an allow-or-challenge decision. Its documentation calls for HTTPS, access to request headers and the end-user IP, and a configurable timeout with a fail-open mechanism.
Check eligibility and integration support. The custom Protection API integration is documented for Premium and Enterprise customers; confirm current account eligibility and requirements in the Protection API reference. A supported module may be more appropriate for your stack.
For AI-agent traffic, complete both integrations. DataDome’s Agentic Trust getting-started guide says the service is built on Bot Protect and requires server-side and client-side integration. An incomplete or misconfigured setup can produce partial or missing traffic data.

The Protection API is an owner-side integration, not an endpoint for an external automation operator to call to grant itself access. Its purpose is for the protected service’s backend to validate incoming traffic and apply the returned decision.

Reliability, performance, and cost considerations

Reliability: Treat challenges, blocks, and timeouts as explicit outcomes to record and escalate. Do not silently retry in a loop; repeated requests can create load and do not establish authorization.
Performance: Keep navigation timeouts bounded and collect only the diagnostics needed to troubleshoot. For owner-side Protection API integrations, follow the documented timeout and fail-open behavior that matches your service’s risk policy.
Operational cost: Browser workers consume compute while waiting for navigation and rendering, including visits that end at a challenge. Budget for authorized retries and human review rather than assuming every run yields usable page data.
Data handling: Request and browser diagnostics may contain URLs, headers, cookies, or page content. Collect and retain only what your organization is allowed to process, and avoid logging secrets.
Vendor cost: DataDome’s pricing and account entitlements are not specified in the cited documentation here. Check with DataDome for current commercial terms and API eligibility.

Troubleshooting

Symptom	Possible cause	Appropriate next step
A challenge or block appears	The site’s bot-protection decision rejected or needs more information about the request; the browser symptom alone does not identify the signal.	Stop automated access and ask the site owner for an approved method. Commercial bots can use the documented authentication request process.
Navigation times out	Network trouble, a slow page, a stalled browser, or an interstitial may be involved.	Record the timeout and final URL, check authorized network access, and ask the owner whether the page should be available to automation. Do not increase retries indefinitely.
HTTP request works but browser automation is challenged	The requests have different browser-side context; DataDome documents client-side checks as part of detection.	Do not infer a single cause. Ask the site owner to inspect its decision data and provide an approved automation path.
Site owner sees missing or incomplete Agentic Trust traffic	The required server-side or client-side integration may be absent or misconfigured.	Review both components against the current Agentic Trust setup guide.
Protection API integration fails or behaves unexpectedly	Request metadata, HTTPS, IP/header access, timeout handling, account eligibility, or the integration itself may not match requirements.	Check the current API reference and account tier; validate the owner-side request path and configured fail-open behavior.
Cookie or JavaScript Tag behavior breaks	The tag may lack access to the `datadome` cookie or its attributes may have been changed.	Review the JavaScript Tag documentation and restore the documented cookie behavior.
The diagnostic script says no challenge, but access is still limited	The sample marker check is only a heuristic and can miss challenge pages or other denial responses.	Use the result only as triage. Check the HTTP status and final URL, then consult the site owner’s decision records.

Frequently asked questions

Does DataDome block every Playwright or Selenium session?

The documentation identifies these automation frameworks among relevant detection categories, but it does not establish that every session is blocked. The site’s policy and detection decision determine the outcome.

Does passing Device Check mean my automation is approved?

No. Device Check may allow, block, or lead to another challenge, and it does not grant authorization from the site owner.

Can a commercial bot request access without changing its identity?

DataDome’s documented commercial-bot process includes using a dedicated user agent and an authentication mechanism, followed by a request. The site owner decides whether to authorize the bot.

Can an automation operator use the Protection API to whitelist itself?

No. The Protection API is an integration for the protected website’s backend to submit request metadata and apply an allow-or-challenge decision.

Where should an AI-agent operator start?

If the agent needs access to a protected site, ask that site’s owner about authorization and the documented bot authentication process. Agentic Trust is a site-owner integration that requires both server-side and client-side setup.