Proxies

Route your browser through an IP in the country you choose. Pick from three kinds of IP (rotating residential, static ISP, and mobile), and optionally reuse the same IP across sessions.

How to turn it on

Pass a proxy object to sessions.create(). country is the only field you need.

type ProxyOptions = {
  // Two-letter country code, lowercase. See the list below.
  country: string

  // Which kind of IP. Default "residential".
  //   "residential": everyday home-internet IPs.
  //   "static":      one fixed IP that stays the same all session.
  //   "mobile":      cellular carrier IPs.
  tier?: "residential" | "static" | "mobile"

  // Reuse one IP across sessions. Pick any short label; sessions that
  // share the label share the IP. Not the same as the Session object.
  session?: string
}

proxy.session vs the SDK Session object

proxy.session is just a label you pick to reuse the same IP. It is not the same thing as the Session object returned by sessions.create().

Examples

// Residential, US.
sessions.create({ stealth: true, proxy: { country: "us" } })

// Residential, GB.
sessions.create({ stealth: true, proxy: { country: "gb" } })

// Static ISP, US: one fixed IP for the whole session.
sessions.create({ stealth: true, proxy: { country: "us", tier: "static" } })

// Mobile, US.
sessions.create({ stealth: true, proxy: { country: "us", tier: "mobile" } })

// Reuse one IP across several sessions: give them the same label.
sessions.create({
  stealth: true,
  proxy: { country: "us", session: "warmup-1" },
})

Proxies require stealth: true.

Choosing a tier

	Residential	Static ISP	Mobile
`tier`	`"residential"` (default)	`"static"`	`"mobile"`
The IP	One exit IP per session; reuse it across sessions with `session`	Stays the same all session	One exit IP per session; reuse it across sessions with `session`
Speed	Varies (home internet)	Fast and steady	Varies (cellular)
Best for	Getting past bot defenses; geo-diverse scraping	IP allowlisting; account-bound sessions	The toughest targets that block residential IPs

Proxy traffic is billed per GB. See Pricing.

Older static: true still works

An earlier version used a static: boolean field. static: true still works and means the same as tier: "static" (as does tier: "isp"). For new code, prefer the tier form.

Supported countries

Pass any of these as the lowercase two-letter code:

Code	Country	Code	Country	Code	Country
`au`	Australia	`de`	Germany	`jp`	Japan
`br`	Brazil	`es`	Spain	`kr`	South Korea
`ca`	Canada	`fr`	France	`mx`	Mexico
`gb`	United Kingdom	`in`	India	`nl`	Netherlands
`sg`	Singapore	`it`	Italy	`us`	United States

Any other code is rejected with a 400 that lists the supported ones.

Reusing the same IP

Use proxy.session when several sessions need to come from the same IP: multi-step logins, account-bound scraping, or any flow where a changing IP triggers a security challenge. Pick any label (letters, numbers, and dashes, up to 32 characters). Sessions created with the same label get the same exit IP; a different label, or no label at all, gets a different one.

What you get back

The session response includes a proxy object confirming the country and tier you were given, plus a timezone that matches the IP's location. The proxy is already applied to the browser, so there is nothing else to set up.

const session = await client.sessions.create({
  stealth: true,
  proxy: { country: "gb" },
})

console.log(session.proxy.country)     // "gb"
console.log(session.proxy.tier)        // "residential"
console.log(session.proxy.timezoneId)  // "Europe/London"

To confirm you actually got a proxied session, check that session.proxy is present rather than checking for a 201.