Proxies

Browserless offers built-in residential and datacenter proxies. 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.

Prerequisites

• A Browserless API token from your account dashboard

Browserless Proxies

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

Network	Description	Cost
residential (default)	Routes through real residential IP addresses. Harder to detect.	6 units/MB
datacenter	Routes through datacenter IPs. Cheaper but more easily detected.	2 units/MB

The datacenter pool covers fewer countries than residential. If a country has no datacenter coverage, requests won't exit from the requested location, so use residential when you need full geographic coverage.

Available proxy parameters:

• proxy=residential - Enables residential proxy routing (6 units/MB)
• proxy=datacenter - Enables datacenter proxy routing (2 units/MB)
• proxyCountry=us - Routes through a specific country (ISO 3166 country codes)
• proxyCity=chicago - Routes through a specific city within the selected country
• proxySticky=true - Keeps one stable exit IP for the whole session. On by default for stealth routes, BrowserQL, /unblock, and /scrape — a mid-session IP change can re-trigger anti-bot systems (Akamai, DataDome) that bind their sensor/cookie to the egress IP. Plain REST endpoints (/content, /pdf, /screenshot, /export, /download, /function) rotate the IP unless you set this. Pass proxySticky=false to opt out of the sticky default.
• proxyPreset=px_gov01 - Website-specific proxy preset (residential only); use px_gov01 for government websites or px_ipv6 for Google domains such as Maps and YouTube

Sticky sessions

A sticky session keeps one stable exit IP for the whole session instead of rotating the IP on each request. This is now the default for stealth routes (/stealth, /chromium/stealth, /chrome/stealth, or any request with ?stealth=true), /scrape, /unblock, and all BrowserQL sessions — because anti-bot systems like Akamai and DataDome bind their sensor and cookies to the egress IP, so a mid-session IP change can re-trigger the block.

Plain non-stealth REST endpoints (/content, /pdf, /screenshot, /export, /download, /function) still rotate the IP by default; add proxySticky=true to pin them.

proxySticky is a real boolean: pass proxySticky=false (or proxySticky=0) to opt out and force IP rotation where sticky is the default.

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 built-in proxies (proxy=residential or proxy=datacenter). Using both returns a 400 error.
• Third-party proxy usage is not billed for proxy units — only Browserless's built-in proxies consume proxy units.

FAQ & Troubleshooting

Why am I getting a 401 Unauthorized error?

Your API token is missing or invalid. Include it as a ?token= query parameter or in the Authorization header. Verify the token in your account dashboard.

My request returns an empty response

The page may not have finished loading. Increase waitForTimeout or use waitForSelector to wait for specific content before extracting data.

Next steps

REST API overview

introduction to all available endpoints

API playground

test endpoints interactively