BrowserQL

BrowserQL (BQL) is a stealth-first browser automation tool. You write GraphQL mutations against managed browsers to navigate pages, interact with elements, extract data, and bypass bot detection.

How It Works

You write GraphQL mutations that describe what the browser should do. Browserless runs the browser, manages stealth configuration, and returns structured results. Run queries through the BQL IDE or send them as HTTP requests from your code.

Here's a minimal example that navigates to Hacker News and extracts the page text:

mutation ScrapeHN {
  goto(url: "https://news.ycombinator.com", waitUntil: domContentLoaded) {
    status
  }
  text {
    text
  }
}

When to Use BrowserQL

BrowserQL is built for sites that actively resist automation. Use it when Puppeteer or Playwright scripts get blocked, when you need automatic CAPTCHA solving, or when you need human-like behavior at scale. For simple automation on permissive sites, Puppeteer or Playwright alone may be enough.

Key Capabilities

• Navigation and waiting: Go to URLs, wait for selectors, network requests, or custom timeouts before proceeding.
• Interaction: Click, type, scroll, and trigger human-like events.
• Data extraction: Return text, attributes, and structured JSON from the page.
• Screenshots and PDFs: Capture full pages or specific elements at any point in a query.
• CAPTCHA solving: Automatically detect and solve reCAPTCHA and image-based challenges.
• Stealth and fingerprinting: Evade bot detection with entropy injection, browser fingerprint mitigations, and the /stealth/bql endpoint.
• Proxies: Route traffic through built-in residential proxies or your own proxy provider.
• Session handoff: Pass a BQL session to Puppeteer or Playwright via the reconnect mutation.

Browser Endpoints

Three endpoints are available, each using a different browser binary:

• /chromium/bql: Open-source Chromium with no telemetry and a minimal fingerprint surface. Best for most headless scraping and automation.
• /chrome/bql: A genuine Google Chrome build. Use when your target site requires or explicitly detects the real Chrome browser, or needs built-in video codec support.
• /stealth/bql: A privacy-hardened browser with fingerprint randomization, ad and tracker blocking, and a distinct user agent. Use when Chrome or Chromium are blocked.

Authentication

Requests to BrowserQL require an API token passed as a query parameter. See the Quick Start guide to get your token and run your first query.

Session Limits

BrowserQL session durations depend on your subscription plan:

Plan	Maximum Session Duration
Free	1 minute
Prototyping (20k)	15 minutes
Starter (180k)	30 minutes
Scale (500k) and above	60 minutes
Enterprise (self-hosted)	Custom

Next Steps

Quick Start

Set up your account and run your first BrowserQL query

Writing BQL

Learn GraphQL mutations, aliases, and BQL syntax

Bot Detection

Bypass CAPTCHAs, fingerprinting, and anti-bot systems