Skip to main content

Proxies

Browserless offers a built-in residential proxy. All REST APIs function the same for proxying: simply add the proxy parameters to your request query strings and you're all done. No need for credentials or otherwise.

Browserless Proxies​

https://production-sfo.browserless.io/content?token=YOUR_TOKEN&proxy=residential&proxyCountry=us

Available proxy parameters:

  • proxy=residential - Enables residential proxy routing
  • proxyCountry=us - Routes through a specific country (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
  • proxyPreset=px_gov01 - Website-specific proxy configuration (use px_gov01 for government websites or px_ipv6 for Google domains such as Maps, YouTube, etc.)
City-Level Proxying

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

To get a list of available cities, use the following endpoints:

  • 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​

https://production-sfo.browserless.io/screenshot?token=YOUR_TOKEN&externalProxyServer=http://user:pass@proxy.example.com:8080

The externalProxyServer query parameter routes traffic through browserless's internal proxy tunnel infrastructure, chaining to your proxy as the upstream. This gives browserless visibility into the connection (bytes tracking, logging) and supports HTTPS certificate bypass automatically.

Pass your proxy URL as a query parameter in the format http(s)://[username:password@]host:port.

Important Notes
  • On cloud plans, third-party proxies require a paid plan. Free plans will receive a 401 error.
  • You cannot combine externalProxyServer with proxy=residential (built-in proxies). Using both returns a 400 error.
  • Third-party proxy usage is not billed for proxy units — only browserless's built-in residential proxies consume proxy units.