Skip to main content
Route browser sessions through proxy servers to access geo-restricted content, rotate IPs, and distribute requests across different locations.
Proxy features require a paid plan.

​
Quick Start

Enable Hyperbrowser’s managed proxy network with a single parameter: 
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const session = await client.sessions.create({
  useProxy: true,
});

console.log("Session ID:", session.id);
console.log("WebSocket endpoint:", session.wsEndpoint);

​
Country-Level Targeting

Target specific countries using ISO 3166-1 alpha-2 country codes. Hyperbrowser supports 100+ countries including:
RegionCountries
North AmericaUS, CA, MX
EuropeGB, DE, FR, ES, IT, NL, SE, CH
Asia PacificJP, AU, SG, IN, KR, HK, CN
South AmericaBR, AR, CL
Middle EastAE, SA, IL
// Target specific countries
const usSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
});

const gbSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "GB",
});

const jpSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "JP",
});

​
US State-Level Targeting

For US proxies, target specific states for more precise geo-targeting: 
// Target California
const caSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
  proxyState: "CA",
});

// Target New York
const nySession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
  proxyState: "NY",
});

// Target Texas
const txSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
  proxyState: "TX",
});
State codes use the standard two-letter US state abbreviations (AL, AK, AZ, AR, CA, etc.)

​
City-Level Targeting

Target specific cities for ultra-precise geo-location. Common cities include New York, Los Angeles, Chicago, London, Tokyo, and more. 
// Target New York City
const nycSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "US",
  proxyCity: "new york",
});

// Target London
const londonSession = await client.sessions.create({
  useProxy: true,
  proxyCountry: "GB",
  proxyCity: "london",
});
proxyCity and proxyState are mutually exclusive. Use one or the other, not both.
While Hyperbrowser supports nearly all countries and a lot of cities, not all areas are guaranteed to be available. Especially for areas with low population density, separate testing should be done to ensure that adequate coverage is available.

​
Custom Proxy Servers

Use your own proxy infrastructure by providing server credentials. Supports HTTP, HTTPS, SOCKS5, SOCKS5h proxies. 
const session = await client.sessions.create({
  useProxy: true,
  proxyServer: "scheme://proxy.example.com:8080",
  proxyServerUsername: "proxy-username",
  proxyServerPassword: "proxy-password",
});
When setting the proxyServer, ensure that you start it with the scheme like http:// for example.

​
Best Practices

Use proxies in the same region as your target content for better performance and to avoid geo-blocking.
Always enable useUltraStealth or useStealth when using proxies to maximize detection evasion.
Verify your proxy configuration works with target sites before running large-scale operations.

Stealth Mode

Advanced bot detection evasion

Static IPs

Use dedicated IP addresses

Profiles

Persist cookies and local storage

Live View

Watch sessions in real-time