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.

The API accepts the lowercase two-letter country codes enumerated by ProxyCountryCode in the current V4 OpenAPI schema. Unsupported values are rejected when the run is created.

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"},
)

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},
)

Custom proxy

Custom HTTP and SOCKS5 proxies require an active subscription. See the pricing page for current commercial terms.

Python

run = client.runs.create(
    "Check the account dashboard",
    browser_settings={
        "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.