Configure a browser proxy

Choose one proxy source

Official proxy and an external 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 project entitlement and available proxy traffic quota. 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.