Skip to main content
proxy.browser-use.com gives you the Browser Use residential proxy outside Browser Use browsers. Use it from curl, an HTTP library, or a browser you run yourself. You log in with your Browser Use API key.
curl
The response is a German residential IP address.
Cloud browsers already use the residential proxy. To set their country, see Proxies. This page is for traffic that does not come from a cloud browser.

Connection

The proxy tunnels HTTPS sites with CONNECT and also forwards plain HTTP requests.
If your client cannot connect to an HTTPS proxy, use http://proxy.browser-use.com:8080. On that port, your API key travels without encryption. Use port 443 when you can.

Username

Start with user. Add the parameters you need, in any order. Each parameter can appear once. The proxy refuses these usernames with 407 and bad_params:
  • An unknown parameter, or a parameter that appears twice.
  • A country code that is not on the ISO list.
  • A session ID that is longer than 36 characters, contains other characters, or has two hyphens in a row.
  • A session ID that contains country, session or policy between hyphens, such as job-session-1.
  • A policy ID that is not a UUID.

Sticky sessions

Send the same session ID to keep the same exit IP across requests and connections. Send a new session ID to request a different IP.
curl
Sticky sessions are best effort. A residential IP can go offline, so the IP of a session can change at any time, also in the middle of a session. Browser Use does not guarantee how long a session keeps its IP. Do not use these IPs for IP allowlisting.
  • Session IDs belong to your project: another project that uses the same session ID gets its own session, not yours. Residential IPs are shared, so other customers can still use the same IP.
  • Keep the same country for all requests of a session.
  • Without a session ID, each connection can use a different IP.

API key

The password is a Browser Use API key. A full-access key works. A restricted key needs Write on proxy (scope v4:proxy:create). With only Read, the proxy answers 407 with key_not_allowed. The proxy endpoint belongs to the US deployment, so use an API key from the US dashboard. The EU deployment has no proxy endpoint.

Network policies

Add -policy-<id> to the username to apply a network policy to every request:
curl
  • A host that the policy blocks gets 403 with blocked.
  • A policy ID from another project gets 403 with policy_not_found.
  • If the proxy cannot load the policy, it refuses the request with 503 and policy_unavailable. It does not send the request without the policy.
  • If the policy is deleted, requests that still name its ID continue without a network policy within a few seconds. The security blocklist still applies.
  • The Browser Use security blocklist always applies first.

Billing

Traffic is billed per GB to the project of the API key, at the same rate as the managed residential proxy of cloud browsers. It counts toward the key’s monthly spend limit. The proxy checks the key, balance and spend limit when a connection opens. Connections that are already open keep running, and keep billing, until they close. See the pricing page for current rates and Billing for how usage is charged.

Examples

Python requests

HTTPS proxies need urllib3 1.26 or later, which current requests installs.
Python

Playwright

Pass the proxy when you launch Chromium. Every page of that browser uses it.
This is your own browser on your own machine. For a managed cloud browser with stealth and the proxy already set up, see the Browser quickstart.

Errors

Errors from the proxy usually carry the reason in the X-Proxy-Error header and at the end of the status line, for clients that hide proxy headers:
For plain HTTP requests, the site’s own responses pass through unchanged. A 403 without X-Proxy-Error came from the site. A 502 without it came from the site or from the proxy. See also Proxies and Network policies.