Targeting options
Options are -key-value pairs appended to your username, freely combinable
and order-independent:
USER-country-us-state-texas-city-houston-sid-s42-ttl-30
Everything before the first known option key is your account username, so a username containing hyphens still works.
Geo
| Option | Values | Notes |
|---|---|---|
country | ISO-2 code, or any | country-us. any = no country constraint |
state / region | name or code | Aliases for the same thing: state-texas |
city | name | city-houston. Approximate; see the caveat below |
asn | number, AS prefix optional | asn-7922 and asn-AS7922 are equivalent |
zip | postal code | zip-77002 |
continent | europe, asia, africa, northamerica, southamerica, oceania, or the short codes eu, as, af, na, sa, oc | Expands to one country in that continent; an explicit country wins |
Multi-word values use no spaces: state-newyork, city-sanfrancisco.
City accuracy. Country, state, and ASN come from a verified measurement of each exit and are reliable. City is approximate: city-level location data is inherently less precise for residential connections. If exact city matters, verify the exit yourself and treat the label as a hint.
Session
| Option | Values | Default | Notes |
|---|---|---|---|
sid / session | any string, ≤60 chars | none | Same sid → same exit. See Sticky sessions |
ttl | minutes, 10-1440 | 10 min | How long a sid stays pinned. Clamped into range |
strict | false/0/off/no to disable | on | See below |
speed | 1-10 | none | Prefer faster exits within the matched set |
quality | low, medium (or med), high | none | Filters on measured network class; high restricts to residential-grade lines |
mobile | flag (no value) | off | Mobile-carrier exits only |
ttl is minutes in the username. ttl-30 is thirty minutes.
Strict mode
Strict is on by default: if nothing matches your exact target, you get
417 rather than a silently broader exit. This matters: a
“US, Texas, Comcast” request should never quietly return a random US IP.
Turn it off to allow progressive widening (asn → city → zip → state;
country and session are never dropped):
USER-country-us-state-texas-city-houston-strict-false
Only false, 0, off, and no disable it. Any other value leaves it on.
Examples
# Rotating US residential
USER-country-us
# A specific carrier
USER-country-us-asn-7922
# Mobile only, high quality
USER-country-gb-mobile-quality-high
# Sticky for 30 minutes
USER-country-de-sid-checkout-42-ttl-30
# City, but accept broader if unavailable
USER-country-us-city-houston-strict-false
# Fastest available exit in Japan
USER-country-jp-speed-10