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.
GatewayRegion
core.eclipseproxy.comAuto-routed
us.core.eclipseproxy.comUnited States
sg.core.eclipseproxy.comSingapore

​
Ports

PortProtocolSession
9000HTTPRotating
10000HTTPSticky
11000SOCKS5Rotating
12000SOCKS5Sticky

​
Format

Two equivalent formats: 
core.eclipseproxy.com:10000:eclipse_yourname-country-kh-state-phnompenh-asn-38901-session-OaUE4kFO-lifetime-30:your_password_here

http://eclipse_yourname-country-kh-state-phnompenh-asn-38901-session-OaUE4kFO-lifetime-30:[email protected]:10000
For SOCKS5, swap http:// for socks5://.

​
Username segments

The username encodes all your targeting and session settings, joined with -: 
eclipse_yourname             ← account
-country-kh                  ← country (ISO 3166-1 alpha-2)
-state-phnompenh             ← state (lowercase, no spaces)
-asn-38901                   ← ASN (must pair with country)
-session-OaUE4kFO            ← sticky session ID
-lifetime-30                 ← lifetime in minutes
-limit-500                   ← per-session bandwidth cap, in MB
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. 
-country-us

​
State / region

Lowercased, no spaces: 
-country-us-state-california
-country-kh-state-phnompenh

​
City

Lowercased, no spaces: 
-country-us-city-losangeles

​
State OR city: not both

You can target either state OR city, not both at the same time. This is a pool-level constraint. 
-country-us-state-california                 ✓
-country-us-city-losangeles                  ✓
-country-us-state-california-city-losangeles ✗

​
ASN

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

​
ISP

-country-us-isp-<name>

​
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. 
-country-fr-asn-3215-strict-off
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

ErrorCause
country-XX-asn-YY target was not foundStrict matching, no IPs available. Try -strict-off or broaden.
ASN should be used with country.ASN without country. Add -country-XX.

​
Exclusions

Use -not. flags to exclude rather than include.
FlagExample
-not.country-XX,YY-not.country-us,ca,mx
-not.state-NAME-not.state-california,newyork
-not.city-NAME-not.city-charlotte,newyork
-not.asn-NUMBER-not.asn-31898,12345
Rule: one exclusion type per request. Can’t mix -not.country- with -not.state- in the same request. Combine exclusions with positive targeting: 
-country-us-not.asn-31898         ← US IP, but not ASN 31898
-not.country-us,ca                ← anywhere except US/Canada

​
Sticky vs rotating

RotatingSticky
IP behaviorNew IP per connectionSame IP for a duration
Port9000 (HTTP) / 11000 (SOCKS5)10000 (HTTP) / 12000 (SOCKS5)
UsernameNo -session- segment-session-<id>-lifetime-<min>
Use forScraping, distributed crawlingLogin, account management, multi-step workflows

​
Sticky session syntax

-session-abc123-lifetime-30
  • 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. 
-session-abc123-lifetime-30-limit-500    ← this session can use up to 500 MB
  • 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