Proxies

Overview

Browserbase offers a flexible proxy system, enabling you to control how your automation traffic is routed across the internet. Whether you need anonymity, geolocation control, or improved reliability, Browserbase makes it easy to integrate proxies into your workflows.

Proxy Configuration Options

With Browserbase, you can:

Use built-in proxies: Effortlessly route traffic through our managed residential proxies.
Bring your own proxies: Use custom HTTP/HTTPS proxies for greater control over network routing.
Combine multiple proxies: Set custom routing rules to direct traffic through different proxies based on domain or location.

Proxies are configured when creating a session through the API or SDK.

Use built-in proxies

Use Browserbase’s built-in proxies to route traffic through managed, residential proxies. This is the simplest option and requires very little setup.

Setting proxies: true will make a best-effort attempt to use a US-based proxy. If nearby US proxies are unavailable, we may route through nearby countries (like Canada).

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithProxies() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    proxies: true,
  });
return session;
}
const session = await createSessionWithProxies();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithProxies() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    proxies: true,
  });
return session;
}
const session = await createSessionWithProxies();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

from browserbase import Browserbase
import os

def create_session_with_proxies():
  bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])
  session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=True
  )
  print("Session URL: https://browserbase.com/sessions/" + session.id)
  return session

session = create_session_with_proxies()

ERR_TUNNEL_CONNECTION_FAILED: indicates either a temporary proxy hiccup or a site unsupported by our built-in proxies (more details below). Please try again or email support@browserbase.com.

Set Proxy Geolocation

Set the geolocation of the proxy to a specific country, state (when within the United States), and city. This is useful if you need to proxy traffic to a specific location. If there is no proxy in the specified location, the closest proxy will be used.

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithGeoLocation() {
  const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    {
      "type": "browserbase",
      "geolocation": {
        "city": "NEW_YORK",
        "state": "NY",
        "country": "US"
      }
    }
  ],
  });
return session;
}
const session = await createSessionWithGeoLocation();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithGeoLocation() {
  const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    {
      "type": "browserbase",
      "geolocation": {
        "city": "NEW_YORK",
        "state": "NY",
        "country": "US"
      }
    }
  ],
  });
return session;
}
const session = await createSessionWithGeoLocation();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def create_session_with_geo_location():
  session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=[
        {
        "type": "browserbase",
        "geolocation": {
            "city": "NEW_YORK",
            "state": "NY",
            "country": "US"
            }
        }
    ]
  )
  print("Session URL: https://browserbase.com/sessions/" + session.id)
  return session

session = create_session_with_geo_location()

Geolocation fields are case-insensitive.

To set geolocations outside of the United States, use the following format:

"geolocation": {
  "city": "LONDON",
  "country": "GB"
}

"geolocation": {
  "city": "LONDON",
  "country": "GB"
}

"geolocation": {
  "city": "TOKYO",
  "country": "JP"
}

"geolocation": {
  "city": "SAO_PAULO",
  "country": "BR"
}

Proxy geolocations by country

Our built-in proxies support 201 countries.

Africa

Asia

Europe

North America

Oceania

South America

Custom Proxies

Browserbase supports custom proxy configurations, allowing you to route traffic through your own HTTP or HTTPS proxies. This is useful if you need to enforce specific network routing rules, comply with security policies, or optimize performance with a preferred proxy provider.

To configure a custom proxy, provide the proxy server URL and authentication details when creating a session.

Browserbase validates proxy connections at session creation time. If we are unable to connect to the specified proxy, an error will be thrown. Ensure that your proxy server is accessible and the provided credentials are correct before creating a session. We also do not support all proxy providers.

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithCustomProxies() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    proxies: [
      {
        "type": "external",
        "server": "http://...",
        "username": "user",
        "password": "pass",
      }
    ]
  });
  return session;
}

const session = await createSessionWithCustomProxies();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithCustomProxies() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    proxies: [
      {
        "type": "external",
        "server": "http://...",
        "username": "user",
        "password": "pass",
      }
    ]
  });
  return session;
}

const session = await createSessionWithCustomProxies();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def create_session_with_custom_proxy():
  session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=[
    {
      "type": "external",
      "server": "http://...",
      "username": "user",
      "password": "pass",
    },
  ]
  )
  print("Session URL: https://browserbase.com/sessions/" + session.id)
  return session

session = create_session_with_custom_proxy()

Proxies Routing Rules

Combine multiple proxies and define routing rules based on domain patterns. This is particularly useful when different websites require different proxies, such as routing government-related sites through one proxy while using another for general browsing.

Proxies are applied in the order they are listed, meaning the first matching rule is used for each request. If no rule matches a domain pattern, you can use the browserbase proxy type to fall back to Browserbase’s default proxies.

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithRouting() {
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    // Use an external proxy for wikipedia.org
    {
      "type": "external",
      "server": "http://...",
      "username": "user",
      "password": "pass",
      "domainPattern": "wikipedia\.org"
    },
    // Use an external proxy for all other .gov domains
    {
      "type": "external",
      "server": "http://...",
      "username": "user",
      "password": "pass",
      "domainPattern": ".*\.gov"
    },
    // Use the Browserbase proxies for all other domains
    // Excluding this line will not use a proxy on any other domains
    {
      "type": "browserbase"
    }
  ]
  });
return session;
}
const session = createSessionWithRouting()
console.log("Session URL: https://browserbase.com/sessions/" + session.id)

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createSessionWithRouting() {
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  proxies: [
    // Use an external proxy for wikipedia.org
    {
      "type": "external",
      "server": "http://...",
      "username": "user",
      "password": "pass",
      "domainPattern": "wikipedia\.org"
    },
    // Use an external proxy for all other .gov domains
    {
      "type": "external",
      "server": "http://...",
      "username": "user",
      "password": "pass",
      "domainPattern": ".*\.gov"
    },
    // Use the Browserbase proxies for all other domains
    // Excluding this line will not use a proxy on any other domains
    {
      "type": "browserbase"
    }
  ]
  });
return session;
}
const session = createSessionWithRouting()
console.log("Session URL: https://browserbase.com/sessions/" + session.id)

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def create_session_with_routing():
  session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    proxies=[
      # Use an external proxy for wikipedia.org
    {
      "type": "external",
      "server": "http://...",
      "username": "user",
      "password": "pass",
      "domainPattern": "wikipedia\.org"
    },
    # Use an external proxy for all other .gov domains
    {
        "type": "external",
        "server": "http://...",
        "username": "user",
        "password": "pass",
        "domainPattern": ".*\.gov"
    },
    # Use the Browserbase proxies for all other domains
    # Excluding this line will not use a proxy on any other domains
    {
      "type": "browserbase"
    }
  ]
  )
  print("Session URL: https://browserbase.com/sessions/" + session.id)
  return session

session = create_session_with_routing()

How is proxy usage measured?

Proxy usage is measured by the total amount of data transferred through the proxy. This includes:

Webpage content, downloads, and media files
HTTP headers, authentication data, and encryption overhead
Any requests and responses routed through the proxy

Since all traffic must pass through the proxy server before reaching its final destination, every interaction contributes to your total bandwidth usage.

To reduce proxy usage, refer to our Cost Optimization section.

Limitations

Certain high-risk categories are restricted by our proxy providers and cannot be accessed through proxies, including:

All Apple domains, including iTunes and App stores
Entertainment (e.g., Netflix, Playstation)
Banking and other financial institutions
Some Google domains
Streaming
Ticketing
Mailing
Some .gov domains

Overview

SDKs

APIs

Overview

Proxy Configuration Options

Use built-in proxies

Set Proxy Geolocation

Proxy geolocations by country

Custom Proxies

Proxies Routing Rules

How is proxy usage measured?

Limitations

Overview

SDKs

APIs

​Overview

​Proxy Configuration Options

​Use built-in proxies

​Set Proxy Geolocation

​Proxy geolocations by country

​Custom Proxies

​Proxies Routing Rules

​How is proxy usage measured?

​Limitations

Overview

Proxy Configuration Options

Use built-in proxies

Set Proxy Geolocation

Proxy geolocations by country

Custom Proxies

Proxies Routing Rules

How is proxy usage measured?

Limitations