Targeting
Control where your proxy IPs come from by appending dash-separated parameters to your username. You can target by country, state, city, or ASN. Your password never changes.
How targeting works
Every targeting choice is encoded in the username you connect with. You keep the same password, endpoint, and port for your product, and only the username changes. Append parameters in dash-separated form:
<username>-country-<cc>[-state-<name>][-city-<name>][-asn-<number>][-session-<id>][-ttl-<minutes>]Parameters in [square brackets] are optional. Omit any you do not need. Order the parameters as shown above. The base username is the one displayed in your dashboard.
http://<username-with-parameters>:<password>@<endpoint>:<port>. See Authentication for the three ways to authenticate.Parameters
The full set of parameters you can append to a username:
| Parameter | Example | Meaning |
|---|---|---|
-country- | -country-us | Two-letter country code (ISO 3166-1 alpha-2), e.g. us, de, gb. |
-state- / region | -state-california | State or region within the chosen country. Residential / ISP uses full state names. |
-city- | -city-losangeles | City within the chosen country (and state, if given). |
-asn- | -asn-7018 | Target a specific network by its ASN number. |
-session- | -session-abc123 | Any string you choose. The same string returns the same sticky IP; change it or omit it to rotate. |
-ttl- | -ttl-30 | How long a sticky session's IP is held, in minutes. |
-ttl-30 holds the IP for 30 minutes, and -ttl-1440 holds it for 24 hours. Maximum sticky durations vary by product. See Sessions & rotation.What each product supports
Not every product accepts every parameter. Use only the parameters supported by your product, because unsupported parameters are not honoured.
| Product | country | state | city | asn | session | ttl |
|---|---|---|---|---|---|---|
| Budget Unlimited | Yes | No | No | No | Yes | Yes |
| Premium Unlimited | Yes | Yes | Yes | No | Yes | Yes |
| Residential / ISP | Yes | Yes | Yes | Yes | Yes | Yes |
| Mobile | Yes | No | No | No | Yes | Yes |
| IPv6 | Yes | No | No | No | Yes | No |
| Static ISP | Each port is already a fixed, dedicated IP, with no rotation or targeting parameters needed. | |||||
Worked examples
The following examples assume a username of user123 and password pass456. Swap in your own dashboard credentials, endpoint, and port for your product.
Country only: US
Route through any IP in the United States, rotating per request:
curl -x "http://user123-country-us:[email protected]:10000" \
https://api.ipify.orgCountry, state and city: US, California, Los Angeles
Narrow down to a specific city (Premium Unlimited or Residential / ISP):
curl -x "http://user123-country-us-state-california-city-losangeles:[email protected]:20228" \
https://api.ipify.orgCountry, ASN and sticky session: US, ASN 7018, held 30 minutes
Target a specific network and keep the same IP for 30 minutes (Residential / ISP):
curl -x "http://user123-country-us-asn-7018-session-job42-ttl-30:[email protected]:20228" \
https://api.ipify.orgReusing the same -session-job42 value returns the same IP until the 30-minute window elapses. Change the session value, or drop it, to rotate to a fresh IP.
Next steps
Sessions & rotation
How -session and -ttl control sticky versus rotating IPs, and the maximum sticky duration per product.
Budget Unlimited
Shared residential, country-level targeting, port-based.
Premium Unlimited
Dedicated-speed residential with country, state and city targeting.
Residential / ISP
Tier-1 ISP-routed residential with full country, state, city and ASN targeting.
Mobile
Real 4G/5G carrier IPs with country-level targeting.
IPv6
Datacenter-grade IPv6 threads with country-level targeting.
Last updated July 6, 2026