Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
BrowserQL (BQL) is Browserless’s GraphQL protocol for controlling managed browsers. Instead of writing a sequence of Puppeteer or Playwright calls, you send an HTTPS POST containing GraphQL mutations that describe navigation, interaction, extraction, screenshots, PDFs and other browser work. Browserless also offers BAP, a typed TypeScript and Python SDK over the same mutations.
BQL is most useful when you want declarative, cross-language workflows or the hosted BQL IDE. For a permissive site and an existing automation script, Browserless says Puppeteer or Playwright may be sufficient. The sections below show how the protocol works, how to choose among Browserless interfaces, and how to avoid common implementation failures.
What BrowserQL is (and is not)
BrowserQL is a software protocol, not a browser or physical device. A BQL request is a GraphQL document containing mutations. Browserless executes those mutations in a managed Chromium, Chrome or stealth browser session and returns structured results.
The vendor describes the model this way: “BrowserQL is a declarative GraphQL API: you describe what the browser should do rather than scripting step-by-step.” In practice, your request can combine actions such as opening a URL, clicking, typing, waiting, extracting text or attributes, and producing a screenshot or PDF.
#1 Best Overall
When BQL is a good fit
- You want one declarative request that can be called from any language with an HTTP client.
- You are prototyping in the hosted BQL IDE, which can manage the endpoint and help generate queries.
- Your workflow needs vendor-documented capabilities such as proxy routing, stealth behavior, CAPTCHA solving or reconnecting a session to Puppeteer or Playwright.
- You are building generated GraphQL operations rather than maintaining a large imperative browser script.
When another interface is simpler
For ordinary sites that do not resist automation, a local Puppeteer or Playwright script can be easier to debug. If you already have such a script and only need managed browsers, Browserless BaaS connects that code over WebSocket. REST APIs are a better shape for stateless tasks such as a single screenshot, PDF, scrape or content extraction request.
How a BrowserQL request works
- Select an endpoint and token. Browserless documents Chromium, Chrome and stealth endpoints. Chromium is intended for most headless automation; Chrome is for cases requiring genuine Chrome or built-in video codec support; stealth is for stronger fingerprint and privacy handling. Endpoint names, regions and token syntax can change, so copy the current values from your Browserless account or documentation.
- Write mutations. Common schema operations include
goto,reject,proxy,click,type,htmlandreconnect. The schema also documents waits, scrolling, text and attribute extraction, structured JSON, screenshots, PDFs, CAPTCHA solving and request controls. - POST GraphQL over HTTPS. Send a JSON body with a
queryproperty and authenticate with your API token as required by the selected endpoint. - Inspect the response. GraphQL returns a
dataobject for successful fields and anerrorsarray when a mutation or argument is invalid. Treat browser-level failures separately from GraphQL validation errors.
Minimal HTTP request
Use the endpoint shown in your Browserless account. Keeping it in an environment variable avoids hard-coding credentials or an endpoint that may later change.
export BROWSERQL_ENDPOINT='https://YOUR-CURRENT-BROWSERLESS-ENDPOINT/graphql'
export BROWSERLESS_TOKEN='YOUR_API_TOKEN'
curl -sS -X POST "$BROWSERQL_ENDPOINT"
-H 'Content-Type: application/json'
-H "Authorization: Bearer $BROWSERLESS_TOKEN"
--data-binary @- <<'JSON'
{"query":"mutation { goto(url: "https://news.ycombinator.com") { status } html(selector: "body") { html } }"}
JSONThe mutation names and return fields must match the schema exposed by your endpoint. If your account uses token query parameters instead of an Authorization header, follow that endpoint’s current authentication instructions. The BQL IDE is the safest place to validate field names before moving a query into code.
A practical BQL workflow
Navigate and extract
Start with goto, then extract only the selector or attributes you need. Prefer a stable semantic selector over a long CSS path. If a page renders asynchronously, add a documented wait for a selector, delay or network-idle condition before extraction.
Interact with a page
Use click and type mutations for forms and controls. A reliable flow normally waits for the target, performs the action, waits for the resulting selector or network idle, and then extracts. Scrolling is available for pages that lazy-load content.
Capture output
BrowserQL documents screenshots and PDFs alongside text and structured JSON extraction. Specify the capture options supported by your schema, and verify that the page has reached the desired state before capturing. For a long page, explicitly choose the full-page behavior documented by your endpoint rather than assuming the viewport will include lazy content.
Control traffic and identity
The documented feature set includes proxy routing, custom headers and browser endpoints with different fingerprint characteristics. Use these controls only where you are authorized to access the site. A stealth endpoint can change fingerprint and privacy handling; it is not a guarantee that a target will permit automation.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchReconnect to a live session
reconnect is intended for handing a managed session back to Puppeteer or Playwright. This is useful when a declarative setup step should be followed by imperative application logic. Keep session identifiers and reconnect data secret, and close sessions when your workflow ends.
BrowserQL, BAP, BaaS or REST?
| Interface | Best fit | What you maintain |
|---|---|---|
| BrowserQL | Declarative GraphQL workflows, generated operations, or the hosted IDE | GraphQL mutations and endpoint authentication |
| BAP | TypeScript or Python projects wanting a typed SDK with a Puppeteer- or Playwright-shaped experience | SDK code over the same BQL mutations |
| BaaS | Existing Puppeteer or Playwright automation that should use managed browsers | Your current script plus a WebSocket connection |
| REST APIs | Stateless screenshots, PDFs, scraping and extraction | HTTP requests and response handling |
| Self-hosted Enterprise | Organizations requiring private deployment on their own infrastructure | Infrastructure, upgrades and operational controls |
Choose based on code shape first, then browser requirements, session duration, deployment privacy and region. A team already invested in Playwright generally has less migration work with BaaS; a generated, language-neutral workflow is a stronger BQL candidate.
Browser endpoint choices
- Chromium: the documented default for most headless automation.
- Chrome: choose when genuine Chrome behavior or built-in video codecs are required.
- Stealth: choose when stronger fingerprint and privacy handling is needed. It improves the browser profile but cannot promise access to every site.
Regional endpoints can reduce latency. Confirm the current endpoint URL, supported browser build and authentication method before deploying; these details are service configuration, not permanent properties of GraphQL.
Session limits, pricing and version caveats
The BrowserQL guide accessed on September 29, 2026 listed these maximum session durations:
| Plan | Maximum session duration |
|---|---|
| Free | 2 minutes |
| Prototyping (20k) | 15 minutes |
| Starter (180k) | 30 minutes |
| Scale (500k) | 60 minutes |
| Enterprise self-hosted | Custom value |
These are a dated guide snapshot, not an evergreen guarantee. The pricing page indicates that longer-running automations may consume additional units. Check the live plan and pricing pages before estimating a production budget. An OpenAPI reference search result reported version 2.56.7; that identifies the reference page and should not be treated as the version of every deployed Browserless component.
Reliability and production practices
Make waits explicit
Never assume a click immediately produces its result. Wait for a selector, a known delay or network idle, then validate the expected text or attribute before continuing.
Keep operations small
Short mutations are easier to retry and diagnose than one very long workflow. Break a multi-page job into checkpoints and persist the data you have already extracted.
Retry safely
Retry transient transport errors and browser startup failures with bounded exponential backoff. Do not blindly replay a mutation that submits a payment, creates an account or changes data; use an idempotency strategy in the target application where available.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Protect secrets and personal data
Store API tokens in a secret manager, redact them from logs, and minimize captured HTML or screenshots when pages contain personal information. Proxy, CAPTCHA and stealth features do not remove your legal or contractual obligations to the site owner.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting BrowserQL
GraphQL validation error
Symptom: the response contains errors before a browser starts. Cause: a mutation name, argument or return field does not match the endpoint schema. Fix: open the schema in the BQL IDE, autocomplete the field, and test the smallest mutation first.
401 or 403 authentication failure
Cause: an expired token, wrong header format or token sent to the wrong endpoint. Fix: create or copy a current token, use the authentication method shown for that endpoint, and keep the token out of source control.
Navigation timeout
Cause: a slow origin, blocked resource or page that never reaches the chosen readiness condition. Fix: use a realistic timeout, wait for a specific selector instead of an indefinite network-idle condition, and log the final browser error. Try the documented browser endpoint appropriate to the site.
Free tools Windows power users keep installed
One-click scans. No signup required.
Empty extraction
Cause: content is rendered after navigation, the selector is wrong, or the content is inside a frame or shadow tree not covered by the selector. Fix: wait for the element, inspect the rendered HTML, and adjust the selector using the IDE’s live result.
Best Value
Bot check or CAPTCHA
Browserless documents CAPTCHA-solving, proxy and stealth-related capabilities, but no provider can guarantee authorization or successful access to every target. Confirm that you have permission, use the documented feature for the site, and handle an unresolved challenge as a failed job rather than looping indefinitely.
Session ends early
Compare the job duration with the plan’s current maximum session value. Long-running automations may also consume additional units. Split work into shorter sessions or move to a plan whose current limits fit the workflow.
Or skip the browser setup
If your goal is simply a dependable website image or PDF rather than an interactive browser workflow, ScreenshotNeo provides a single screenshot API call. It accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each cleanup step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemscURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for the full parameter set. It supports full-page captures with lazy images loaded, CSS-selector element shots, dark mode, 12 device presets and custom viewports, retina scale, PDF paper sizes and page ranges, HTML/CSS rendering, custom JavaScript and CSS, clicks, waits, ad and tracker blocking, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for 100 URLs per call, usage data and an OpenAPI specification. Parameters used by other screenshot APIs also work, easing migration.
ScreenshotNeo also has an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Is BrowserQL the same thing as GraphQL?
It uses GraphQL syntax and transport, but BrowserQL adds a browser-automation schema and a managed execution environment; a generic GraphQL server cannot run BQL mutations.
Can I combine BrowserQL with Playwright?
Yes. Browserless documents reconnecting a BQL session to Puppeteer or Playwright, allowing a declarative setup phase followed by existing imperative code.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Does BrowserQL handle bot detection?
Browserless documents stealth behavior, proxy routing and CAPTCHA-solving capabilities. They are tools, not a guarantee of access, authorization or successful completion on every site.
Where should I check current limits?
Check the live Browserless endpoint, plan and pricing documentation immediately before deployment because session limits, units and endpoint details can change.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
