Proxies

Consistent geolocation and network identity for your browser sessions

Overview

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.

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

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

SDK

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);

Python

SDK

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()

Proxy geolocation

Set the proxy geolocation by country, state (within the United States), or city. Browserbase’s built-in proxies support 200+ countries. It’s useful when you need to proxy traffic to a specific location.

Geolocation routing is best effort. If there’s no proxy in the specified location, the closest proxy is used.

Use the broadest geography that meets your needs: start with a country, and a city (or state) only when necessary. Broader geographies provide more proxies to choose from and better outcomes.

Node.js

SDK

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": {
        "country": "US"
      }
    }
  ],
  });
return session;
}
const session = await createSessionWithGeoLocation();
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

Python

SDK

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": {
            "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:

United Kingdom

"geolocation": {
  "country": "GB"
}

Japan

"geolocation": {
  "country": "JP"
}

Brazil

"geolocation": {
  "country": "BR"
}

São Paulo

// Specify city only when necessary
"geolocation": {
  "city": "SAO_PAULO",
  "country": "BR"
}

Supported countries

Browserbase’s built-in proxies support 200+ 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)

Site restrictions

Browserbase’s built-in residential proxies use third-party providers, each with its own acceptable-use policies. Providers may restrict high-risk sites and categories to prevent network abuse. These are provider-level restrictions, not a Browserbase-specific blocklist. Access through proxies may be less reliable for the following categories:

• 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

Whether a domain works depends on the specific proxy provider used for that session and that provider’s current restrictions. Because providers and restrictions can vary over time, the same domain may work in one session and fail in another. Test your target site and confirm it works before relying on it. If it doesn’t, try combinations of Verified with and without proxies. Some sites only need Verified, some need neither, and others need both.

These categories are illustrative, not exhaustive. If access to a specific domain is critical to your workflow, contact [e-mail] for guidance or to confirm whether a specific site is supported.

Troubleshoot proxy errors

ERR_TUNNEL_CONNECTION_FAILED can indicate a site unsupported by Browserbase’s built-in proxies, an unsupported city, or a temporary proxy issue.

• Try accessing the site without proxies (some sites are proxy-restricted)
• If specifying a city, retry without it or with a different city
• Retry the session to rule out a temporary proxy issue

If you need a specific city that isn’t currently supported, contact [e-mail]. We may be able to support it.

Custom proxies

Route traffic through your own HTTP or HTTPS proxies for custom network rules, security policies, or preferred providers.

Configure a custom proxy

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

SDK

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);

Python

SDK

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

SDK

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();

Python

SDK

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

SDK

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);

Python

SDK

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

SDK

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)

Python

SDK

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()

Plans and billing

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.