Skip to content
NextProxyNextProxyDocs

Dynamic residential

Per-gigabyte residential proxies with country-to-city targeting, operator ASN and OS targeting, and 1–120 minute sticky sessions.

The line with the richest targeting: the only one that supports operator ASN targeting, alongside city-level targeting, OS targeting and sticky session options. Billed per gigabyte, which suits workloads with many requests but small payloads.

Premium residential and Mobile are also billed per gigabyte but keep separate balances; the same sub-account switches to them by adding type-premium / type-mobile to the username.

Billing and packages

  • Unit: GB
  • Two purchase shapes:
    • Fixed packages (package) — preset gigabyte tiers
    • Custom volume (custom) — you name the number of gigabytes; the code caps at 1,000,000 GB, with the real range bounded by each product's minGb / maxGb
  • Quote validity: 5 minutes by default, shortened if a promotion or the product's delisting comes sooner. An expired quote must be re-requested.
  • Balance: purchases accumulate into the account's traffic pool. There is no code-level automatic expiry or forfeiture in the current implementation.

Supported targeting options

This line supports every targeting dimension, appended to the username in this order. A username without type (or with type-residential) uses dynamic residential:

OptionValuesNotes
countryTwo uppercase lettersMust be uppercase; us is rejected
state or region1–100 bytesFully equivalent keys; cannot be used together
city1–100 bytesExact match, case-sensitive
asnNumber, optional AS prefixThis is how you target an operator; 64512, AS64512, as64512 all work
oswindows, android, ios, macChoose the proxy exit device’s operating system; Any leaves it unrestricted
session1–64 bytes, [A-Za-z0-9.-]Must appear with time
timeInteger 1–120Minutes; must appear with session

Full escaping rules, ordering constraints and failure examples are in Username option reference.

shell
# Los Angeles + 30 minutes sticky
curl -x 'http://USERNAME-country-US-state-California-city-Los%20Angeles-session-job1-time-30:PASSWORD@GATEWAY_HOST:58971' \
  https://api.ipify.org

# Operator targeting (Comcast's AS7922). asn can't be combined with state or city
curl -x 'http://USERNAME-country-US-asn-7922-session-job1-time-30:PASSWORD@GATEWAY_HOST:58971' \
  https://api.ipify.org

OS targeting works on its own or with location targeting. For example, request a US iOS exit:

shell
curl -x 'http://USERNAME-country-US-os-ios:PASSWORD@GATEWAY_HOST:58971' \
  https://api.ipify.org

Real-world limits on targeting

Valid targeting options still require an available matching IP. Keep these limits in mind:

  • State and city targeting depends on whether that country is opened down to that level. City targeting in practice requires country and state to be supplied too.
  • Available ASN options are listed in the console catalogue.
  • Selecting an operating system restricts results to proxy IPs matching that system.
  • Combining ASN with state or city may be unavailable; use these filters separately.
  • Session duration can be set from 1 to 120 minutes.

When no available IP matches the selected filters, the request returns HTTP 503 service_unavailable (SOCKS5 reply 0x01). Remove filters one at a time and retry.

Sessions and rotation

With session + time: the same proxy account, session value and filters keep the same exit IP for time minutes. An exit device going offline can affect IP availability.

Without session: every new TCP connection receives a newly assigned exit IP, which may repeat a previous result.

The same session value with different operating systems uses separate sessions. Sticky sessions do not guarantee a permanently fixed IP. Use static residential when you need a long-term fixed IP.

More detail in Sticky sessions and rotation.

Metering

Only bytes carried in either direction over established connections are counted, including the tunnel handshake.

Counted: the handshake of an established tunnel (the CONNECT request headers and the 200 Connection Established reply; the SOCKS5 greeting, authentication, request and reply), everything after the CONNECT tunnel is established (TLS records, HTTP headers, bodies), the reconstructed request headers in ordinary forward mode, upload plus download.

Not counted: connections that are never established, the gateway-to-exit handshake (including retries on another exit), TCP/IP packet headers.

Billed traffic is then multiplied by a product multiplier and floored after accumulation. Details in Traffic accounting.

Where it fits

Good fit

  • Web scraping, price comparison, SERP collection
  • Verification work that needs city- or operator-level precision
  • Short multi-step flows that need stickiness (log in → paginate → submit)

Poor fit

Programmatic extraction

Besides composing usernames directly, the Extract API hands back a batch of ip:port entries for passwordless access via source-IP whitelisting. That suits setups where region and session configuration live on the server and clients only receive a list of ports.

Dynamic residential OS targeting is available only for username/password access, not the Extract API. To extract ports with an operating system, use premium residential (product=premium&os=...). Choose Windows, Android, iOS, or macOS in the generator; Any omits the os option.

Did this page solve your problem?