Skip to main content
Residential is the most flexible product, with the most setup options. This page covers all of them.

​
Generator

Unified Proxy Generator — select Residential as the product.

​
Gateways

Pick the gateway closest to your traffic source.

​
Ports

​
Format

Two equivalent formats:
For SOCKS5, swap http:// for socks5://.

​
Username segments

The username encodes all your targeting and session settings, joined with -:
All segments after the account name are optional. The minimum valid username is just your account name.

​
Targeting

​
Country

ISO 3166-1 alpha-2 codes: us, gb, de, fr, it, es, br, in, kh, etc. We cover 190+ countries. The dashboard generator dropdown is the source of truth for what’s currently available.

​
State / region

Lowercased, no spaces:

​
City

Lowercased, no spaces:

​
State OR city: not both

You can target either state OR city, not both at the same time. This is a pool-level constraint.

​
ASN

Specific ISP networks. Must be paired with country:
ASN alone returns {"proxy-error":"ASN should be used with country."}.

​
ISP

​
Strict matching and fallback

By default, if your targeting can’t be satisfied (no IPs available for that combo), you get a proxy-error. Add -strict-off to opt into fallback: the system returns any available IP in the country.
Use strict (default) when you’d rather an explicit error than the wrong geo. Use -strict-off when you’d rather any IP in the country than no IP.

​
Errors

​
Exclusions

Use -not. flags to exclude rather than include. Rule: one exclusion type per request. Can’t mix -not.country- with -not.state- in the same request. Combine exclusions with positive targeting:

​
Sticky vs rotating

​
Sticky session syntax

  • Same session-abc123 returns the same IP across requests
  • After lifetime-30 minutes, the session expires
  • Different session IDs return different IPs

​
Lifetime values

Common: 1, 5, 10, 30, 60, 120, 1000 minutes. For sticky beyond a few hours, the upstream residential IP may rotate before lifetime expires (out of our control). For guaranteed stability, use ISP.

​
Per-session bandwidth cap (-limit-)

Add a -limit-<MB> segment to cap how much bandwidth a single session may consume. It’s an optional control for keeping individual sessions from burning through more data than you intend.
  • Units: megabytes (MB).
  • Scope: per session. The cap applies to the specific -session-<id> it’s attached to, not your whole account.
  • Behavior: once the session transfers more than the limit, further requests on that session fail with error 467 (Session bandwidth limit). Switch to a new session ID to keep going.
This is independent of your account-wide balance: running out of account bandwidth returns error 466 instead.

​
”Why does session ID change when I change lifetime?”

The dashboard generator regenerates a random session ID alongside any change. They aren’t linked: to keep the same session ID with a different lifetime, copy the session ID manually.

​
Authentication

User:pass (default) or IP whitelist. See Authentication.

​
Pool basics

  • ~1 million IPs across 190+ countries
  • Pool changes constantly as residential users come online/offline
  • Threads unlimited on Residential
  • GB you buy never expires

​
Things to watch for

  • “All my generated proxies look the same”: normal for rotating; each connection rotates at the gateway
  • “Wrong country IP”: usually a username typo or no inventory for that city; verify with curl -x ... https://ipinfo.io. See Wrong country IP
  • “City has no inventory”: try -strict-off or broaden to state/country
  • “Protocol mismatch error”: using HTTP creds on SOCKS port or vice versa; re-generate with correct port