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

​
Update Proxy on a Running Session

You can update proxy settings on an active session without recreating it by calling PUT /session/:id/update with type: "proxy".
  • Set enabled: false to disable proxying for the current session.
  • Set enabled: true with staticIpId to switch the session onto a static IP.
  • Set enabled: true with an optional location object to use Hyperbrowser’s managed proxy network.
  • If location.country is omitted, Hyperbrowser defaults it to US.
  • Custom proxy values cannot be set through this update route. If you need proxyServer, proxyServerUsername, or proxyServerPassword, create the session with those values instead.
  • Once a session has used managed proxy or static IP, you can disable and re-enable that same proxy type, but you cannot switch between managed proxy and static IP within the same session.

​
Managed Proxy Update

Use location to target a managed proxy location on an existing session. 
await client.sessions.updateProxyParams(session.id, {
  enabled: true,
  location: {
    country: "GB",
    city: "london",
  },
});

// If country is omitted, it defaults to US.
await client.sessions.updateProxyParams(session.id, {
  enabled: true,
  location: {
    state: "CA",
  },
});

​
Static IP Update

Provide staticIpId to move an existing session onto one of your team’s active static IPs. 
await client.sessions.updateProxyParams(session.id, {
  enabled: true,
  staticIpId: "YOUR_STATIC_IP_ID",
});

​
Disable Proxy

Disable proxying for the active session without ending the session itself. 
await client.sessions.updateProxyParams(session.id, {
  enabled: false,
});

​
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