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 - Maintains the same proxy IP across the session
• 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

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