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 / -region-california | State within the chosen country, always the full state name. Premium Unlimited uses -state-<full name>; Residential / ISP uses -region-<full name>. Multi-word names use underscores, e.g. -region-new_york. |
-city- | -city-los_angeles | City within the chosen country (and state, if given). Multi-word names use underscores. |
-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 |
|---|---|---|---|---|---|---|
| Premium Unlimited | Yes | Yes | Yes | Yes | Yes | Yes |
| Residential / ISP | Yes | Yes | Yes | Yes | Yes | Yes |
| Mobile | Yes | No | No | No | No | No |
| 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. Without a session tag the endpoint holds one US IP until it rotates; add a fresh -session value per request for a new IP on every request:
curl -x "http://user123-country-us:[email protected]:20228" \
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-region-california-city-los_angeles:[email protected]:20228" \
https://api.ipify.orgOn Residential / ISP the state parameter is -region-<full state name>; on Premium Unlimited use -state-california instead, against your dedicated endpoint on port 8000.
Country, 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, city and ASN 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 10, 2026