Proxies

A US residential proxy is enabled by default. The browser’s traffic passes through that residential IP before reaching the website, so the website sees the proxy’s location—not your server’s.

A cloud browser routing its traffic through a residential proxy before reaching a website

Set browser_settings / browserSettings when you create a V4 run to choose another country:

The current TypeScript SDK type requires proxyCountryCode whenever browserSettings is present. Use "us" to keep the default, or null to disable the managed proxy.

from browser_use_sdk.v4 import BrowserUse

client = BrowserUse()
run = client.runs.create(
    "Get the iPhone 16 price on amazon.de",
    browser_settings={"proxyCountryCode": "de"},
)

import { BrowserUse } from "browser-use-sdk/v4";

const client = new BrowserUse();
const run = await client.runs.create({
  task: "Get the iPhone 16 price on amazon.de",
  model: "grok-4.5",
  browserSettings: { proxyCountryCode: "de" },
});

curl https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"Get the iPhone 16 price on amazon.de",
       "browserSettings":{"proxyCountryCode":"de"}}'

Disable proxies

Pass null for QA or internal sites that do not need a residential proxy:

run = client.runs.create(
    "Test my staging site",
    browser_settings={"proxyCountryCode": None},
)

const run = await client.runs.create({
  task: "Test my staging site",
  model: "grok-4.5",
  browserSettings: { proxyCountryCode: null },
});

Custom proxy

Custom proxies are available to all accounts, including free and pay-as-you-go accounts. No subscription is required. Normal credit, spend, and concurrency limits still apply. The request format depends on what you are creating:

REST endpoint	Custom proxy field
`POST /api/v4/browsers`	Top-level `customProxy`
`POST /api/v4/runs`	`browserSettings.customProxy`

browser_settings is the Python SDK keyword for agent runs. In REST JSON, the agent-run field is browserSettings.

Standalone browsers

For a browser you control with Playwright, Puppeteer, or another CDP client, put customProxy directly in the request body:

curl

curl https://api.browser-use.com/api/v4/browsers \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customProxy": {
      "host": "proxy.example.com",
      "port": 8080,
      "username": "YOUR_PROXY_USERNAME",
      "password": "YOUR_PROXY_PASSWORD"
    }
  }'

Replace the proxy details with yours. Omit both username and password if your proxy does not require authentication. Do not wrap these settings in browserSettings or browser_settings on /api/v4/browsers. Keep the returned browser ID and stop the browser with PATCH /api/v4/browsers/{id} and {"action":"stop"} when finished. See the Create browser reference and Browser quickstart.

Agent runs

For a hosted agent, pass the proxy in the run’s browser settings:

run = client.runs.create(
    "Check the account dashboard",
    browser_settings={
        "customProxy": {
            "host": "proxy.example.com",
            "port": 8080,
            "username": "user",
            "password": "pass",
            "ignoreCertErrors": False,
        }
    },
)

const run = await client.runs.create({
  task: "Check the account dashboard",
  model: "grok-4.5",
  browserSettings: {
    proxyCountryCode: "us",
    customProxy: {
      host: "proxy.example.com",
      port: 8080,
      username: "user",
      password: "pass",
      ignoreCertErrors: false,
    },
  },
});

A custom proxy overrides proxyCountryCode and must be passed again when a follow-up provisions a new browser. See the Create run reference for the complete settings object.

Get Started

Pillars

More

Disable proxies

Custom proxy

Standalone browsers

Agent runs

​Disable proxies

​Custom proxy

​Standalone browsers

​Agent runs

Disable proxies

Custom proxy

Standalone browsers

Agent runs