Configure a browser proxy

Choose one proxy source

Official proxy, external proxy, and SDK local proxy are mutually exclusive session options. They affect browser traffic; do not assume that an SDK's own API requests or a separate Web Fetch call use the same proxy.

const session = await client.sessions.create({
  browserMode: 'normal',
  officialProxy: true,
});

Official proxy use requires available project proxy traffic quota. Each usage period includes 100 MB for Free and 1 GB for Pro, Pro+, and Enterprise. Upload and download traffic both count toward this allowance; new official-proxy sessions are blocked once it is exhausted. A custom upstream requires credentials from your proxy provider:

const session = await client.sessions.create({
  browserMode: 'normal',
  proxy: {
    type: 'external',
    server: process.env.PROXY_SERVER!,
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD,
  },
});

Set PROXY_SERVER to the provider's proxy address, including the scheme and port, for example http://proxy.example.net:8080. These are alternative creation snippets, not two calls to execute in sequence. Close the created session in finally.

Verify the route

Use an IP-check endpoint you control or trust from inside the browser page. Compare the observed egress with the provider's expected route, then test the actual target site. An HTTP 200 from session creation does not prove proxy authentication or target access succeeded. Never include proxy passwords in screenshots, URLs shared with others, or logs.

For 407, check upstream authentication. For connection failures, verify scheme, port, provider allowlists and network reachability. A successful proxy request does not guarantee access to every website. See troubleshooting and runnable proxy demos.

SDK Local Proxy

To reach company, VPN, or development sites accessible from the SDK machine, open client.tunnels.open() and create a normal browser session with proxy.type=local. See the local proxy guide for complete Node.js/Python examples, region requirements, lifecycle, and troubleshooting.