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

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

Certain high-risk categories are restricted by Browserbase’s proxy providers and can’t 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

Welcome

Platform

Use cases

Optimization

Account

Proxy configuration options

Use built-in proxies

Set proxy geolocation

Proxy geolocations by country

Custom proxies

Proxy routing rules

Who can use proxies?

How is proxy usage measured?

Limitations

Welcome

Platform

Use cases

Optimization

Account

​Proxy configuration options

​Use built-in proxies

​Set proxy geolocation

​Proxy geolocations by country

​Custom proxies

​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

Proxy routing rules

Who can use proxies?

How is proxy usage measured?

Limitations