Proxies

Browserbase offers a flexible proxy system that gives your browser sessions consistent geolocation and network identity. Whether you need location-specific content, consistent IP addresses across sessions, or traffic routing control, proxies ensure your automation runs from the right place every time. Proxies pair well with Verified sessions for the best experience on protected sites.

Proxy configuration options

With Browserbase, you can:

Use built-in proxies: Effortlessly route traffic through Browserbase’s 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.

View or run the example template here

Use built-in proxies

Use Browserbase’s built-in proxies to route traffic through managed, residential proxies. This is the simplest option and only requires setting the proxies property to true when creating the session. By default, proxies is set to false.

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

Node.js
Python

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

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

async function createSessionWithProxies() {
  const session = await bb.sessions.create({
    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(
    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 Browserbase’s 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. It’s useful when you need to proxy traffic to a specific location. If there’s no proxy in the specified location, the closest proxy is used.

Node.js
Python

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

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

async function createSessionWithGeoLocation() {
  const session = await bb.sessions.create({
  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(
    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:

London, UK
Tokyo, Japan
São Paulo, Brazil

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

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

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

Proxy geolocations by country

Browserbase’s built-in proxies support 201 countries.

Africa

🇩🇿 Algeria (DZ)
🇦🇴 Angola (AO)
🇧🇯 Benin (BJ)
🇧🇼 Botswana (BW)
🇧🇫 Burkina Faso (BF)
🇧🇮 Burundi (BI)
🇨🇲 Cameroon (CM)
🇨🇻 Cape Verde (CV)
🇨🇩 Democratic Republic of the Congo (CD)
🇪🇬 Egypt (EG)
🇬🇶 Equatorial Guinea (GQ)
🇸🇿 Eswatini (SZ)
🇪🇹 Ethiopia (ET)
🇬🇦 Gabon (GA)
🇬🇲 Gambia (GM)
🇬🇭 Ghana (GH)
🇬🇳 Guinea (GN)
🇬🇼 Guinea-Bissau (GW)
🇨🇮 Ivory Coast (CI)
🇰🇪 Kenya (KE)
🇱🇸 Lesotho (LS)
🇱🇷 Liberia (LR)
🇱🇾 Libya (LY)
🇲🇬 Madagascar (MG)
🇲🇼 Malawi (MW)
🇲🇱 Mali (ML)
🇲🇷 Mauritania (MR)
🇲🇺 Mauritius (MU)
🇾🇹 Mayotte (YT)
🇲🇦 Morocco (MA)
🇲🇿 Mozambique (MZ)
🇳🇦 Namibia (NA)
🇳🇪 Niger (NE)
🇳🇬 Nigeria (NG)
🇨🇬 Republic of the Congo (CG)
🇷🇪 Reunion (RE)
🇷🇼 Rwanda (RW)
🇸🇳 Senegal (SN)
🇸🇨 Seychelles (SC)
🇸🇱 Sierra Leone (SL)
🇸🇴 Somalia (SO)
🇿🇦 South Africa (ZA)
🇸🇸 South Sudan (SS)
🇸🇩 Sudan (SD)
🇹🇿 Tanzania (TZ)
🇹🇬 Togo (TG)
🇹🇳 Tunisia (TN)
🇺🇬 Uganda (UG)
🇿🇲 Zambia (ZM)
🇿🇼 Zimbabwe (ZW)

Asia

🇦🇫 Afghanistan (AF)
🇦🇲 Armenia (AM)
🇦🇿 Azerbaijan (AZ)
🇧🇭 Bahrain (BH)
🇧🇩 Bangladesh (BD)
🇧🇹 Bhutan (BT)
🇧🇳 Brunei (BN)
🇰🇭 Cambodia (KH)
🇨🇳 China (CN)
🇬🇪 Georgia (GE)
🇭🇰 Hong Kong (HK)
🇮🇳 India (IN)
🇮🇩 Indonesia (ID)
🇮🇷 Iran (IR)
🇮🇶 Iraq (IQ)
🇮🇱 Israel (IL)
🇯🇵 Japan (JP)
🇯🇴 Jordan (JO)
🇰🇿 Kazakhstan (KZ)
🇰🇼 Kuwait (KW)
🇰🇬 Kyrgyzstan (KG)
🇱🇦 Laos (LA)
🇱🇧 Lebanon (LB)
🇲🇴 Macao (MO)
🇲🇾 Malaysia (MY)
🇲🇻 Maldives (MV)
🇲🇳 Mongolia (MN)
🇲🇲 Myanmar (Burma) (MM)
🇳🇵 Nepal (NP)
🇴🇲 Oman (OM)
🇵🇰 Pakistan (PK)
🇵🇸 Palestine (PS)
🇵🇭 Philippines (PH)
🇶🇦 Qatar (QA)
🇷🇺 Russia (RU)
🇸🇦 Saudi Arabia (SA)
🇰🇷 South Korea (KR)
🇱🇰 Sri Lanka (LK)
🇹🇼 Taiwan (TW)
🇹🇯 Tajikistan (TJ)
🇹🇭 Thailand (TH)
🇹🇷 Turkey (TR)
🇦🇪 United Arab Emirates (AE)
🇺🇿 Uzbekistan (UZ)
🇻🇳 Vietnam (VN)
🇾🇪 Yemen (YE)

Europe

🇦🇽 Aland (AX)
🇦🇱 Albania (AL)
🇦🇩 Andorra (AD)
🇦🇹 Austria (AT)
🇧🇾 Belarus (BY)
🇧🇪 Belgium (BE)
🇧🇦 Bosnia and Herzegovina (BA)
🇧🇬 Bulgaria (BG)
🇭🇷 Croatia (HR)
🇨🇾 Cyprus (CY)
🇨🇿 Czech Republic (CZ)
🇩🇰 Denmark (DK)
🇪🇪 Estonia (EE)
🇫🇴 Faroe Islands (FO)
🇫🇮 Finland (FI)
🇫🇷 France (FR)
🇩🇪 Germany (DE)
🇬🇮 Gibraltar (GI)
🇬🇷 Greece (GR)
🇬🇬 Guernsey (GG)
🇭🇺 Hungary (HU)
🇮🇸 Iceland (IS)
🇮🇪 Ireland (IE)
🇮🇲 Isle of Man (IM)
🇮🇹 Italy (IT)
🇯🇪 Jersey (JE)
🇽🇰 Kosovo (XK)
🇱🇻 Latvia (LV)
🇱🇹 Lithuania (LT)
🇱🇺 Luxembourg (LU)
🇲🇹 Malta (MT)
🇲🇩 Moldova (MD)
🇲🇪 Montenegro (ME)
🇳🇱 Netherlands (NL)
🇲🇰 North Macedonia (MK)
🇳🇴 Norway (NO)
🇵🇱 Poland (PL)
🇵🇹 Portugal (PT)
🇷🇴 Romania (RO)
🇷🇸 Serbia (RS)
🇸🇰 Slovakia (SK)
🇸🇮 Slovenia (SI)
🇪🇸 Spain (ES)
🇸🇪 Sweden (SE)
🇨🇭 Switzerland (CH)
🇺🇦 Ukraine (UA)
🇬🇧 United Kingdom (GB)

North America

🇦🇮 Anguilla (AI)
🇦🇬 Antigua and Barbuda (AG)
🇦🇼 Aruba (AW)
🇧🇸 Bahamas (BS)
🇧🇧 Barbados (BB)
🇧🇿 Belize (BZ)
🇧🇲 Bermuda (BM)
🇻🇬 British Virgin Islands (VG)
🇨🇦 Canada (CA)
🇰🇾 Cayman Islands (KY)
🇨🇷 Costa Rica (CR)
🇨🇺 Cuba (CU)
🇨🇼 Curacao (CW)
🇩🇲 Dominica (DM)
🇩🇴 Dominican Republic (DO)
🇸🇻 El Salvador (SV)
🇬🇱 Greenland (GL)
🇬🇩 Grenada (GD)
🇬🇵 Guadeloupe (GP)
🇬🇹 Guatemala (GT)
🇭🇹 Haiti (HT)
🇭🇳 Honduras (HN)
🇯🇲 Jamaica (JM)
🇲🇶 Martinique (MQ)
🇲🇽 Mexico (MX)
🇳🇮 Nicaragua (NI)
🇵🇦 Panama (PA)
🇵🇷 Puerto Rico (PR)
🇰🇳 Saint Kitts and Nevis (KN)
🇱🇨 Saint Lucia (LC)
🇻🇨 Saint Vincent and the Grenadines (VC)
🇸🇽 Sint Maarten (SX)
🇹🇹 Trinidad and Tobago (TT)
🇹🇨 Turks and Caicos Islands (TC)
🇻🇮 U.S. Virgin Islands (VI)
🇺🇸 United States (US)

Oceania

🇦🇺 Australia (AU)
🇫🇯 Fiji (FJ)
🇵🇫 French Polynesia (PF)
🇬🇺 Guam (GU)
🇫🇲 Micronesia (FM)
🇳🇨 New Caledonia (NC)
🇳🇿 New Zealand (NZ)
🇲🇵 Northern Mariana Islands (MP)
🇵🇬 Papua New Guinea (PG)

South America

🇦🇷 Argentina (AR)
🇧🇴 Bolivia (BO)
🇧🇷 Brazil (BR)
🇨🇱 Chile (CL)
🇨🇴 Colombia (CO)
🇪🇨 Ecuador (EC)
🇬🇫 French Guiana (GF)
🇬🇾 Guyana (GY)
🇵🇾 Paraguay (PY)
🇵🇪 Peru (PE)
🇸🇷 Suriname (SR)
🇺🇾 Uruguay (UY)
🇻🇪 Venezuela (VE)

Custom proxies

Route traffic through your own HTTP or HTTPS proxies for custom network rules, security policies, or preferred providers. 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 Browserbase can’t connect to the specified proxy, an error is thrown. Ensure your proxy server is accessible and credentials are correct before creating a session. Not all proxy providers are supported.

Node.js
Python

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

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

async function createSessionWithCustomProxies() {
  const session = await bb.sessions.create({
    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(
    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()

Trusted CA certificates

When your custom proxy performs TLS interception with a private certificate authority, the browser session must trust that CA, or HTTPS requests through the proxy will fail with certificate errors. This is common with corporate egress proxies, enterprise MITM appliances, and self-hosted gateways. Browserbase lets you upload one or more PEM-encoded CA certificates to your project and reference them by ID when creating a session via proxySettings.caCertificates. Browserbase resolves each ID to the certificate’s PEM content and installs it into the session’s trust store before the browser starts. This is also useful when you need to intercept HTTPS traffic with your own tooling and want the browser to trust your test CA without disabling certificate validation entirely.

Upload a certificate

Upload your CA certificate to your project. Provide a PEM-encoded file containing one or more certificate blocks, up to 100 MB.

Node.js
Python

import { Browserbase, toFile } from "@browserbasehq/sdk";
import { readFile } from "node:fs/promises";

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

async function uploadCertificate() {
  const pem = await readFile("./corporate-ca.pem");
  const certificate = await bb.certificates.create({
    file: await toFile(pem, "corporate-ca.pem"),
  });
  console.log("Certificate ID:", certificate.id);
  return certificate;
}

const certificate = await uploadCertificate();

from browserbase import Browserbase
import os

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

def upload_certificate():
  with open("./corporate-ca.pem", "rb") as f:
    certificate = bb.certificates.create(file=f)
  print("Certificate ID:", certificate.id)
  return certificate

certificate = upload_certificate()

You can also list, retrieve, and delete uploaded certificates. See the Certificates API reference for details.

Each certificate belongs to the project the API key belongs to and persists until you delete it. Browserbase validates that the uploaded file is a parseable PEM certificate at upload time.

Use a certificate in a session

Pass the certificate ID(s) on proxySettings.caCertificates when creating the session. Browserbase installs your certificates alongside the system trust store, so public CAs continue to work normally.

Node.js
Python

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

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

async function createSessionWithTrustedCA() {
  const session = await bb.sessions.create({
    proxies: [
      {
        type: "external",
        server: "http://corporate-proxy.example.com:8080",
        username: "user",
        password: "pass",
      },
    ],
    proxySettings: {
      caCertificates: ["<certificate-id>"],
    },
  });
  return session;
}

const session = await createSessionWithTrustedCA();
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_trusted_ca():
  session = bb.sessions.create(
    proxies=[
      {
        "type": "external",
        "server": "http://corporate-proxy.example.com:8080",
        "username": "user",
        "password": "pass",
      },
    ],
    proxy_settings={
      "ca_certificates": ["<certificate-id>"],
    },
  )
  print("Session URL: https://browserbase.com/sessions/" + session.id)
  return session

session = create_session_with_trusted_ca()

caCertificates accepts an array, so you can trust multiple custom CAs in a single session. If any ID doesn’t exist or doesn’t belong to your project, session creation fails with a 400.

Proxy routing rules

Combine multiple proxies and define routing rules based on domain patterns. It’s 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. Excluding domains from proxies: To exclude certain domains from using proxies, list the excluded domains first with "type": "none", followed by your proxy configuration:

[
  {
    "type": "none",
    "domainPattern": "^([a-zA-Z0-9-]+\\.)*(example\\.com|test\\.com|demo\\.com)$"
  },
  {
    "type": "browserbase",
    "geolocation": {}
  }
]

Proxy rules are evaluated in order, and the first matching rule is used. By placing the exclusion pattern first with "type": "none", those domains won’t use a proxy, while all other domains will match the second rule and use Browserbase proxies.

Node.js
Python

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

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

async function createSessionWithRouting() {
const session = await bb.sessions.create({
  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(
    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()

Who can use proxies?

Anyone on a Developer Plan or higher can use both Browserbase’s built-in proxies and custom proxies. Find more information about included proxy GBs by plan on the pricing page.

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 the cost optimization guide.

Proxy billing: Sessions using Browserbase proxies have a 1 MB minimum. Any usage thereafter is rounded to the nearest MB.

Limitations

Browserbase’s built-in residential proxies are sourced from third-party proxy providers, and those providers restrict certain high-risk site categories under their own acceptable use policies to prevent network abuse. These restrictions apply at the provider level, not as a Browserbase-specific blocklist, so:

Support isn’t a blanket yes/no per site. Whether a domain works through proxies: true depends on the specific proxy provider routed for that session and its current restrictions, which can change over time.
Test your target site directly. Before relying on built-in proxies for a protected or high-risk site, run a session against it and confirm it works. If it doesn’t, try combinations of Verified with and without proxies. Some sites only need Verified, others need both.

Sessions targeting these categories carry a higher risk of lower reliability across Browserbase’s proxy providers, since providers apply their own acceptable use restrictions to them:

Banking and financial services: banks, credit unions, payment processors, card networks, and cryptocurrency exchanges
Government domains: including most .gov sites
Streaming and entertainment: video/audio streaming platforms and services like Netflix, Spotify, and gaming platforms (e.g., PlayStation, Steam)
Ticketing: sites like Ticketmaster and Eventbrite
Webmail providers: e.g., Outlook, Yahoo Mail
Gambling: online casinos, betting, and wagering sites

These categories are illustrative, not exhaustive. Each proxy provider maintains its own restricted-target list and updates it independently. If a session against a specific domain fails with a proxy-related error (see ERR_TUNNEL_CONNECTION_FAILED above), treat that as the source of truth for that domain rather than this list. Contact support@browserbase.com if you need to confirm whether a specific site is supported.

Welcome

Platform

Use cases

Optimization

Account

Proxy configuration options

Use built-in proxies

Set proxy geolocation

Proxy geolocations by country

Custom proxies

Trusted CA certificates

Upload a certificate

Use a certificate in a session

Proxy routing rules

Who can use proxies?

How is proxy usage measured?

Limitations

​Proxy configuration options

​Use built-in proxies

​Set proxy geolocation

​Proxy geolocations by country

​Custom proxies

​Trusted CA certificates

​Upload a certificate

​Use a certificate in a session

​Proxy routing rules

​Who can use proxies?

​How is proxy usage measured?

​Limitations

Proxy configuration options

Use built-in proxies

Set proxy geolocation

Proxy geolocations by country

Custom proxies

Trusted CA certificates

Upload a certificate

Use a certificate in a session

Proxy routing rules

Who can use proxies?

How is proxy usage measured?

Limitations