Targeting
Every parameter you can put in a proxy username, with the rules on how they combine.
Targeting is written into the username as key-value pairs joined by hyphens, after the pool selector. Keys and values are lowercase. Omit a parameter and the network chooses for you.
Pool selector
Always first.
| Selector | Pool |
|---|---|
network-residential: | Residential IPs, desktop devices by default |
network-residential-pool-udp: | Residential IPs verified for UDP over SOCKS5 |
pool-mobile: | Mobile 4G / 5G carrier IPs |
Parameters
| Parameter | Example | Values | Notes |
|---|---|---|---|
country: | country-us | ISO 3166-1 alpha-2 | Several countries: country-de,gb,us, comma-separated, no spaces |
region: | region-texas, region-england | A region code from List regions and cities | Requires country |
city: | city-london, city-losangeles | A city code from List regions and cities | Requires country; cannot be combined with asn |
asn: | asn-3320 | An ASN from List ASNs, without the AS prefix | Requires country; cannot be combined with city |
os: | os-windows | windows, macos, linux, android, ios | Operating system of the device behind the IP |
session: | session-a91f3 | Any string you choose | Same id, same IP, until the TTL expires or the IP goes offline. Omit for a new IP on every request |
ttl: | ttl-60 | Minutes, 1 to 1440 | How long a session holds its IP. Only meaningful with session |
zip: | — | — | Not available yet |
Where the codes come from
Region and city values are codes, not names you type: california, losangeles, england. The locations endpoint of the User API lists the codes available in each of your plan’s countries. ASNs come from List ASNs, searched by name or number; that list is global, so pick an ASN that operates in the country you target. Guessing a code gives 417.
Generate proxies builds complete usernames for you, including asn and os. Which parameters a plan accepts is in its targeting block, returned by Get a plan.
Rules
- Order matters only for the pool selector, which must come first. The other parameters can appear in any order.
cityandasnare exclusive. A request with both is rejected. Pick the one that matters more, or useregionwithasn.- Multiple countries spread requests across all of them; you cannot weight one over another.
ttlwithoutsessiondoes nothing: there is no session to hold.- Device type is desktop on
network-residential. To get mobile devices, use thepool-mobilepool rather thanos-androidoros-ios, which select the operating system of a residential device, not a carrier IP. - Unknown keys or values make the gateway reject the request with
407.
Full example
network-residential-country-us-region-california-city-losangeles-os-windows-session-394893-ttl-120
A residential IP in Los Angeles, California, on a Windows device, held for two hours under session 394893.
Availability
Coverage varies by country and by how narrow the target is. Country-level targeting is available everywhere the network has IPs; city and asn depend on local pool size. If a narrow request returns no IP, widen it one step: city to region, region to country.