Skip to main content

Proxies

BrowserQL supports built-in residential proxies and external third-party proxies. Use built-in proxies for IP rotation, geographic routing, and session stickiness. Use external proxies to route traffic through your own proxy provider.

Built-In Proxies​

BrowserQL's built-in residential proxies route your requests through real residential IP addresses. This helps bypass geographic restrictions and reduces the chance of IP-based detection.

You can configure:

  • Proxy country: Route requests through a specific country.
  • Sticky proxying: Reuse the same IP across multiple requests in a session.
Proxy Cost

Built-in proxies consume 6 units per MB of traffic.

Enable via the IDE​

  1. Open the Session Settings Panel.
  2. Toggle Residential Proxying to On.
  3. Set Sticky Proxying to reuse the same IP, or set Proxy Country to target a specific location.

Enable Programmatically​

Add proxy parameters directly to your BQL endpoint URL:

https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&proxy=residential

Available parameters:

  • proxy=residential: Enables residential proxy routing.
  • proxyCountry=us: Routes through a specific country. Accepts ISO 3166 country codes.
  • proxyCity=chicago: Routes through a specific city within the selected country.
  • proxySticky=true: Maintains the same proxy IP across the session.
  • proxyLocaleMatch=true: Sets the browser language to match the proxy location (for example, Portuguese for Brazil).
  • proxyPreset=px_gov01: Applies a website-specific proxy preset. Use px_gov01 for government websites or px_ipv6 for Google domains such as Maps and YouTube.
  • externalProxyServer: Routes traffic through your own proxy server. Format: http(s)://[username:password@]host:port. URL-encode the value.
City-Level Proxying

City-level proxying requires a Scale plan (500k+ units). Plans under 500k units receive a 401 error.

To get available cities:

  • All supported cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN
  • Cities for a specific country: https://production-sfo.browserless.io/proxy/cities?country=US&token=YOUR_TOKEN

External Proxies​

Use the proxy mutation to route traffic through your own proxy server. The mutation accepts a server URI and lets you scope which requests get proxied by URL pattern, HTTP method, or request type.

The server URI follows the format protocol://username:password@host:port. Omit the credentials if your proxy doesn't require authentication.

Proxy All Requests​

Use url: "*" to route all requests through the proxy:

mutation ExternalProxy {
  proxy(server: "http://john:1337@myproxy.com:1234" url: "*") {
    time
  }
  goto(url: "https://nordvpn.com/what-is-my-ip/", waitUntil: load) {
    status
  }
  waitForTimeout(time: 5000) {
    time
  }
}

Scope Requests by Type​

You can limit proxying to specific request types instead of all traffic. This is useful when you only need to proxy document loads and API calls, not static assets:

mutation ProxyDocumentAndXHR {
  proxy(server: "http://john:1337@myproxy.com:1234" type: [document, xhr]) {
    time
  }
  goto(url: "https://nordvpn.com/what-is-my-ip/", waitUntil: load) {
    status
  }
  waitForTimeout(time: 5000) {
    time
  }
}

Mix and Match Proxies​

You can define multiple proxy mutations in a single query. BrowserQL uses the first proxy that matches a given request, so order matters.

The example below routes document and XHR requests through a residential proxy and all other requests through a datacenter proxy. The residential proxy is listed first so it takes priority for those request types:

mutation MixedProxies {
  # Proxy document and XHR through residential
  residential: proxy(server: "http://john:1337@residential.proxy.com:1234" type: [document, xhr]) {
    time
  }
  # Proxy all other requests through datacenter
  datacenter: proxy(server: "http://john:1337@datacenter.proxy.com:1234" url: "*") {
    time
  }
  goto(url: "https://nordvpn.com/what-is-my-ip/", waitUntil: load) {
    status
  }
  waitForTimeout(time: 5000) {
    time
  }
}

Reducing Bandwidth​

The reject mutation blocks requests before they're sent. Use it to skip loading images, media, or other assets you don't need. This reduces bandwidth consumption and can speed up page loads.

Bot Detection Risk

Blocking requests can trigger bot detection on some sites. Avoid rejecting resources the target site uses for fingerprinting or session validation. Test your configuration carefully before relying on it in production.

You can reject requests by:

  • URL pattern: Glob-style patterns to match specific domains or paths.
  • HTTP method: Block specific request methods such as GET or POST.
  • Resource type: Filter by type, such as image, media, or script.
  • Operator: Use and to require all conditions to match, or or to match any one of them.
mutation RejectImages {
  reject(type: [image, media]) {
    enabled
    time
  }
  goto(url: "https://en.wikipedia.org/wiki/Main_Page", waitUntil: firstContentfulPaint) {
    status
    time
  }
}
tip

The reject mutation only blocks requests during query execution. Assets may still appear to load in the BrowserQL editor after the mutation completes.

Next Steps​

Solving CAPTCHAs

Handle Cloudflare, reCAPTCHA, and others automatically with built-in CAPTCHA solving support.

Scrape and Extract Data

See how to combine proxies, stealth, and data extraction in a complete scraping workflow.

Performing Searches

Use proxies with geographic routing to run location-aware searches at scale.