Bot Detection
BrowserQL includes built-in tools for bypassing bot detection on protected and heavily monitored pages. This section covers the stealth route, proxies, CAPTCHA solving, and browser fingerprinting.
- A Browserless API token from your account dashboard
- Familiarity with BQL language basics
Using a proxy
BrowserQL supports residential and third-party proxies for bypassing IP-based blocks and location restrictions. See the Proxies documentation for configuration and usage.
Solving CAPTCHAs
BrowserQL includes built-in support for solving Cloudflare, reCAPTCHA, and other challenge types. See the Solving CAPTCHAs documentation for techniques and form submission patterns.
Recommended strategy for protected sites
When working with heavily protected sites, layer your bypass techniques progressively rather than enabling everything at once. This helps you identify what each site requires while minimizing resource usage.
Start with stealth: Run your queries on the stealth route (/stealth/bql) first. If you still encounter blocks, add the techniques below.
Add proxies when needed: If you encounter IP-based blocks or CAPTCHAs, enable residential proxies via the proxy mutation. Residential proxies are more effective than datacenter IPs at bypassing detection, though they consume additional units per MB of traffic.
Use conditional CAPTCHA solving: When CAPTCHAs appear, use the if mutation with a selector to trigger solving only when a CAPTCHA is present. For example, wrap your solve mutation in if(selector: "#g-recaptcha-response") to conditionally execute it. This saves time and resources compared to always attempting to solve.
Set generous timeouts: CAPTCHA solving can take 30 seconds to several minutes depending on the challenge type. Use generous timeout values on your solve mutations. When in doubt, omit the timeout parameter to use the default.
Human-like fingerprints
BrowserQL automatically configures browser sessions to appear indistinguishable from genuine user activity. You can further customize browser binaries, ad-blocking, and mouse and typing behavior patterns. These options are available in Launch Parameters.
FAQ & Troubleshooting
My script is still getting blocked after enabling stealth
Stealth alone may not be enough for heavily protected sites. Combine the /stealth/bql endpoint with residential proxies and human-like behavior. Some sites also require solving CAPTCHAs before proceeding.
Which browser binary should I use for bot-detected sites?
Start with /stealth/bql. If that's blocked, try /chrome/bql with residential proxies. The stealth binary has the most comprehensive fingerprint mitigations, but some sites specifically check for a genuine Chrome user agent.