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.

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.

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
  }
}

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, hCaptcha, 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.

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.

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