Proxies

Managed proxy egress in three tiers — rotating residential, static ISP, and mobile carrier — with country, sticky-IP, and ASN targeting.

Shape

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

type ProxyOptions = {
  // ISO-3166-1 alpha-2, lowercase. See list below.
  country: string

  // Tier. Default "residential".
  //   "residential" — rotating consumer-ISP IPs.
  //   "static"      — datacenter-with-ISP-routing, fixed per session.
  //   "mobile"      — 3G/4G/5G carrier IPs (T-Mobile USA by default).
  tier?: "residential" | "static" | "mobile"

  // Sticky-IP id — pins the same exit IP across requests for the
  // configured duration. Unrelated to the SDK's Session object.
  session?: string

  // Sticky-IP lifetime in minutes (1–30, default 10). Only with session.
  sessionDuration?: number

  // US-only geo narrowing for rotating residential. Ignored on mobile.
  state?: string  // e.g. "california"
  city?: string   // e.g. "los_angeles"

  // Pin egress to a specific ASN. e.g. "7922" (Comcast), "701" (Verizon),
  // "21928" (T-Mobile USA — auto-pinned on tier: "mobile" without asn),
  // "20057" (AT&T Mobility), "6167" (Verizon Wireless).
  asn?: string
}

proxy.session vs the SDK Session object

proxy.session is a sticky-IP tag — a short string you pick to pin the exit IP across requests. It is not the same thing as the Session object returned by sessions.create().

Examples

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

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

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

// Mobile carrier, US — T-Mobile USA by default.
sessions.create({ stealth: true, proxy: { country: "us", tier: "mobile" } })

// Mobile carrier, US, pin AT&T.
sessions.create({
  stealth: true,
  proxy: { country: "us", tier: "mobile", asn: "20057" },
})

// Sticky residential — same IP for 10 minutes across requests.
sessions.create({
  stealth: true,
  proxy: { country: "us", session: "warmup-1", sessionDuration: 10 },
})

// US-only geo narrowing (rotating residential).
sessions.create({
  stealth: true,
  proxy: { country: "us", state: "california", city: "los_angeles" },
})

Proxies require stealth: true.

Tiers

	Residential	Static ISP	Mobile
`tier`	`"residential"` (default)	`"static"`	`"mobile"`
IP continuity	Per request; sticky 1–30 min via `session`	Same IP across the session	CGNAT'd; rotates per request
Pricing	Per-GB	Per-IP per-month	Per-GB (~2–3× residential)
Latency	Variable (home internet)	Datacenter-grade	Variable (cellular RTT)
State / city pinning	US only	Not supported	Not supported
Best for	Bot-defense bypass; geo-diverse scraping	IP allowlisting; account-bound sessions	CF enterprise, Akamai BMP; targets that per-IP-flag residential

Legacy: static: true

The original two-tier API used a static: boolean field. It still works — static: true is silently treated as tier: "static", and tier: "isp" is accepted as a back-compat alias for the same. New callers should prefer the explicit tier form.

Supported countries

Pass any of these as the lowercase ISO-3166-1 alpha-2 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

Mobile is US-centric by default

On tier: "mobile" without an explicit asn, the gateway pins T-Mobile USA (ASN 21928). For non-US mobile, pass the target country's carrier ASN explicitly — otherwise the request falls through to the broader pool and the egress IP will be residential.

Sticky IPs

Use proxy.session when you need the same exit IP across multiple requests — multi-step logins, account-bound scraping, or any flow where a changing IP triggers a security challenge. Pick any string (alphanumeric + dashes, ≤32 chars). Lifetime defaults to 10 minutes; set proxy.sessionDuration to override (1–30 min).

ASN

Pin egress to a specific ISP — useful for IP-reputation arbitrage on top-tier residential ASNs (e.g. 7922 Comcast, 701 Verizon, 21928 T-Mobile) or for ISP-conditional content testing. On tier: "mobile", asn is also how you choose a carrier other than the T-Mobile USA default — pass "20057" for AT&T Mobility, "6167" for Verizon Wireless.

Resolved credentials

The session response carries a proxy object with the resolved server, credentials, country, tier, and an IANA timezone aligned with the egress IP. The proxy is auto-applied to the browser — you don't need to re-apply at the context level.

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

console.log(session.proxy)
// {
//   server:     "http://...",
//   username:   "...",
//   password:   "***",
//   country:    "gb",
//   tier:       "residential",
//   timezoneId: "Europe/London",
// }