Username option reference
All nine username options: accepted values, ordering constraints, dependencies, and a full list of valid and invalid examples.
Product, region, operating system and session configuration all live in the username, separated by -. This is the authoritative reference — malformed published options are rejected; option keys outside the whitelist are silently ignored.
Overall format
base-username-key-value-key-value:password
For example:
alice-country-US-state-California-city-Los%20Angeles-session-job1-time-30
The gateway splits the username on - and scans from the second segment for the first published option key or reserved option key. Once one is found, everything from that segment on is parsed as key-value pairs; only published keys are read and all others are ignored. If none is found, the whole string is treated as a plain username.
The options
The product this connection uses: residential (dynamic residential), premium (premium residential) or mobile (mobile). Without it the connection uses the sub-account's own product.
Not bound by option order; it may appear anywhere: alice-type-premium-country-US and alice-country-US-type-premium are equivalent. Only these three lowercase values are accepted; anything else is rejected, and it may not appear twice.
Only dynamic residential sub-accounts can switch to premium or mobile; the connection draws from that product's balance. When that balance is 0, including a product never bought, the connection returns 402 traffic_exhausted. Other kinds of sub-account switching product return 400 invalid_proxy_parameters.
Premium residential and mobile locations follow their own catalogues and have no asn; mobile has no os either.
Two uppercase ASCII letters, such as US, DE, JP.
Case-sensitive: us is rejected, not normalised to US. The gateway validates only the "two uppercase letters" shape, not membership in ISO 3166-1 — so ZZ passes validation but fails to connect because no matching IP is available.
State, province or region name, 1–100 bytes after decoding.
Like city, matched exactly and case-sensitively; the value must be spelled exactly as it appears in the geography catalogue.
A fully equivalent alias for state, written to the same field.
Cannot be used together with state — they share an ordinal, so the second one is flagged as out of order and rejected.
City name, 1–100 bytes after decoding, matched exactly and case-sensitively.
City targeting in practice requires country and state to be supplied as well.
Autonomous system number — this is the parameter for operator targeting. There is no separate ISP parameter, because an operator is identified by its ASN number.
Bare digits or an AS prefix both work: 64512, AS64512, as64512 are equivalent. After stripping the prefix it must be a positive integer between 1 and 4294967295. The raw value is capped at 20 bytes.
The proxy generator in the console lets you search this field by operator name; what goes into the username is the number, not the name.
Choose the operating system of the device providing the proxy IP. Accepts only lowercase windows, android, ios, or mac (macOS). Any leaves the operating system unrestricted, so the generator does not add -os-xxx to the username. Omit this option when configuring an unrestricted connection manually.
For example, os-ios selects proxy IPs provided by iOS devices. It does not change your own operating system or browser User-Agent.
Supported on dynamic residential and premium residential (type-premium), not on mobile. It can be used alone or combined with location targeting; on dynamic residential also with ASN. Selecting an operating system restricts results to proxy IPs matching that system.
The Extract API accepts os only with product=premium; dynamic residential OS targeting needs username/password access.
Session identifier, 1–64 bytes after decoding, restricted to ASCII letters, digits, . and -.
Case-sensitive: Job1 and job1 are two different sessions.
Must be supplied together with time.
Session duration in minutes, a decimal integer from 1 to 120. The raw value is capped at 3 bytes.
Must be supplied together with session.
Ordering is mandatory
Options must appear strictly in this order:
country → state/region → city → asn → os → session → time
You may skip intermediate options, but you may not reorder them. type is outside the ordering and may go anywhere.
# Valid: state and city skipped
USERNAME-country-US-asn-701-session-a1-time-15
# Invalid: city before country → rejected
USERNAME-city-LA-country-US
Two shapes are rejected; one is ignored
Out of order — any option appearing before its designated position
Duplicated — the same key twice, including state and region together
Unknown key — ignored without being added to the routing identity or carried to the exit. For example, isp-UCB does not take effect. There are no abbreviations like co, st or sid; the only alias is state = region
isp and lifetime are reserved unpublished option keys. They are recognised and ignored even before the first published option. A completely unknown key used on its own immediately after the base username may still be treated as part of that username, preserving compatibility with existing hyphenated account names.
Escaping rules for values
Values are split on bare - first, then each value is URL-path-decoded once. So:
| To express | Write | Notes |
|---|---|---|
| Space | %20 | New York → New%20York |
| Hyphen | %2D | Winston-Salem → Winston%2DSalem |
| Percent sign | %25 | Must be a valid percent escape |
Allowed inside values: internal spaces (escaped), Unicode characters.
Forbidden: leading or trailing whitespace, :, CR, LF, NUL, other Unicode control characters.
Lengths count UTF-8 bytes, not characters — a CJK character counts as three bytes.
Length limits
| Item | Limit |
|---|---|
| Full username | 1–255 bytes |
| Base username (before the options) | 1–64 bytes |
| Password | 1–512 bytes |
One subtle ambiguity
The parser scans from the second segment for the first known key. That creates an edge case:
alice-pool-admin → treated as a plain username (pool is not a known key)
alice-country-US-pool-y → reads country and ignores pool
If your base username happens to contain a segment named type, country, city, session or similar, it will be read as an option key. Console-generated usernames never hit this, but hand-composed ones can.
Valid examples
alice-country-US-region-CA-city-LosAngeles-session-abc.1-time-30
alice-country-US-state-New%20York-city-Winston%2DSalem
alice-country-US
alice-asn-AS64512
alice-os-ios
alice-country-US-os-mac-session-job1-time-30
alice-session-job%2D123-time-120
alice-type-premium-country-US-os-windows
alice-country-GB-state-England-city-London-type-premium
alice-type-mobile-country-US-session-job1-time-10
alice-pool-admin
The last one is not option syntax at all, just an ordinary base username.
Invalid examples
| Input | Why it is rejected |
|---|---|
alice-os-linux | os only accepts windows, android, ios, or mac |
alice-type-datacenter | type only accepts residential, premium, or mobile |
alice-type-Premium | type must be lowercase |
alice-type-premium-country-US-type-mobile | type duplicated |
alice-country-us | country must be uppercase |
alice-city-LA-country-US | Out of order |
alice-country-US-country-CA | Duplicated |
alice-country-US-state-CA-region-California | state and region are the same key |
alice-session-x | session without time |
alice-time-30 | time without session |
alice-session-x-time-0 | time must be ≥ 1 |
alice-session-x-time-121 | time must be ≤ 120 |
alice-country-US-city-Winston-Salem | Unescaped hyphen inside a value |
Dependencies and capability constraints
In addition to supplying session and time together, 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 too
- Available
asnoptions are listed in the console catalogue - With
os, the request fails if no available IP matches the selected operating system - Combining
asnwith state or city may be unavailable; use these filters separately - Session duration can be set from 1 to 120 minutes; mobile sessions round up to one of 1, 5, 10, 30, 60 or 120 minutes
- Premium residential and mobile states and cities follow their own catalogues; outside the US, premium residential has no route for a state without a city
- Premium residential and mobile have no
asn; mobile has noos
Correct syntax with no available matching IP returns HTTP 503 service_unavailable; invalid syntax returns 400 invalid_proxy_parameters. The distinction is covered in the error reference.
What a malformed option returns
Invalid published-option syntax (out of order, duplicated, out-of-range value, missing dependency) → HTTP 400 invalid_proxy_parameters, and for SOCKS5 a failure in the authentication sub-negotiation (01 01). Unknown option keys are ignored and have no effect on the request.
HTTP / CONNECT errors include X-NextProxy-Error and safe JSON. Invalid option syntax uses invalid_proxy_parameters; the original credential-bearing username is never echoed. Check the rules above one option at a time.