Proxies

Route API V4 agent runs through residential or custom 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.

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.

Python

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:

Python

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 HTTP and SOCKS5 proxies are available on paid plans:

Python

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.