Start here · Targeting & sessions

Everything you want from the exit, written into the username.

Country, US state, city, provider, session identity and lifetime. Six parameters, in any order, on both shared gateways.

4 min read 6 sections Updated Sep 21, 2026

Syntax#

Start with your username, then append -key-value pairs. Keys and values are lowercase; order does not matter; the password is unchanged. With no parameter at all the exit is chosen from any country and changes on every connection.

Anatomy

USER-cc-us-state-tx-city-austin-sid-a1b2c3-ttl-30m:PASS
│    │     │        │           │          │
│    │     │        │           │          └─ hold it for 30 minutes
│    │     │        │           └─ session id: same id, same IP
│    │     │        └─ city (letters and digits only)
│    │     └─ US state (United States only)
│    └─ country, ISO 3166-1 alpha-2
└─ your username

Parameters#

Parameter	Values	Meaning
-cc-	Two-letter country code: `us`, `de`, `br`, `jp`	Exit from that country. 199 countries on residential; the mobile pool covers the countries listed at checkout.
-state-	US state code: `tx`, `ca`, `ny`	Exit from that state. Requires `-cc-us`; not available for other countries.
-city-	City name, lowercase, letters and digits only: `newyork`, `berlin`, `saopaulo`	Exit from that city. Requires `-cc-`. Each country page lists its available cities with the exact value.
-asn-	Autonomous system number without the `AS` prefix: `7922`, `3320`	Exit announced by that provider. Combine with `-cc-`. On the mobile pool this is how you pick a carrier.
-sid-	Letters and digits, up to 32 characters: `a1b2c3`, `job42`	Sticky session. Requests carrying the same id share one exit until the lifetime ends or the device goes offline. A new id means a new IP.
-ttl-	Minutes or hours, from `1m` to `24h`: `10m`, `2h`	Lifetime of a sticky session, counted from its first request. Default `10m` when `-sid-` is present without `-ttl-`.

Rotation and sessions#

Without -sid- the gateway picks a new exit for every new connection it receives. Clients that keep a connection alive, or that send many requests through one CONNECT tunnel, keep the same exit for as long as that connection lives. To rotate on every request, disable keep-alive or close the connection after each call; to keep one IP across connections, use a session id.

Same -sid- value, same IP, on any number of parallel connections. Run as many sessions at once as you need; there is no cap.
When the lifetime expires or the household disconnects, the next request with that id gets a new IP that still matches the other parameters. Design for this: an IP change mid-flow is possible on any residential network.
To force a change immediately, change the id. Ids are scoped to your account and cost nothing.
Sticky sessions exist on the residential and mobile pools. Dedicated ISP, datacenter and mobile-device proxies are one fixed IP and ignore -sid- and -ttl-.

Examples#

You want	Username
A new IP in any country on every connection	USER
A new United States IP on every connection	USER-cc-us
A Texas household	USER-cc-us-state-tx
Any IP in Berlin	USER-cc-de-city-berlin
One Berlin IP held for ten minutes	USER-cc-de-city-berlin-sid-7f3a9
One Japanese IP held for two hours	USER-cc-jp-sid-tokyo1-ttl-2h
A Comcast subscriber (AS7922)	USER-cc-us-asn-7922
Deutsche Telekom mobile customers, held 15 minutes	USER-cc-de-asn-3320-sid-m1-ttl-15m
Twenty parallel Brazilian sessions	USER-cc-br-sid-w01 … USER-cc-br-sid-w20

City names#

A city value is the city name in lowercase ASCII with spaces, hyphens, apostrophes and accents removed: New York becomes newyork, São Paulo becomes saopaulo, Düsseldorf becomes dusseldorf, Frankfurt am Main is listed as frankfurt. Use the value printed on the country page rather than guessing; that is the exact string the gateway matches.

What happens when a parameter cannot be honoured#

Case	Response	What to do
Unknown key or malformed value (`-country-us`, `-ttl-90x`)	`400 Bad Request`	Fix the string; the response body names the parameter.
`-city-` or `-state-` without `-cc-`, or `-state-` outside the US	`400 Bad Request`	Add `-cc-us` or drop the parameter.
No exit currently online for the combination (a small city plus one ASN, for instance)	`502 Bad Gateway`	Retry, then broaden: drop `-asn-`, then `-city-`.
Parameters sent to a dedicated address	Ignored	Nothing; the IP is fixed.