Username option reference
All eight username options: accepted values, ordering constraints, dependencies, and a full list of valid and invalid examples.
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
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.
Available for dynamic residential username/password access. It can be used alone or combined with location or ASN targeting. Selecting an operating system restricts results to proxy IPs matching that system. The Extract API does not support this option.
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.
# 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, type-residential and isp-UCB do not take effect. There are no abbreviations like co, st or sid; the only alias is state = region
type, 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 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-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-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
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.