Full reference for SOAX residential proxies. Covers how routing works, session types, geo-targeting, connection parameters, and limits.
Residential proxies route your traffic through real home internet connections. The IPs belong to genuine ISP subscribers, which makes them difficult for websites to detect and block.SOAX’s residential pool includes over 155 million IPs across 195+ countries, with targeting available down to city level.
When you send a request through SOAX, the system selects a node from the residential pool that matches your targeting parameters (country, city, ISP, etc.). Your request is sent through that node to the target website, and the response comes back to you.The target website sees the node’s residential IP address, not yours. Because these IPs are assigned by real ISPs to real households, most anti-bot systems treat them as legitimate traffic.You control which nodes are eligible for your requests using filtering parameters, and you control how long you stay on the same node using session and rotation parameters.
When you don’t include a session parameter, every request gets a new node. No state is maintained between requests. This is the simplest mode and works well for high-volume scraping where you don’t need IP continuity.
When you include a session parameter, the system binds your session to a node. All subsequent requests with the same session ID reuse that node, giving you the same IP.
Run this multiple times and you’ll see the same IP, as long as the session is active and the node is available.Session lifetime:
Sessions expire after 60 seconds of inactivity (no requests sent).
If the bound node becomes unavailable, the system replaces it based on your error handling rules.
Session ID rules:
You choose the session ID (any string you want).
Allowed characters: letters, digits, and underscores.
Maximum length: 32 characters.
Rules are locked on the first request for a given session ID. If you send a second request with the same session ID but different rules, the request is rejected with 409 SESSION_PARAMS_MISMATCH. To change rules, use a new session ID.
You can target residential nodes by country, region, city, ISP, or ASN. These parameters filter which nodes are eligible for your requests.
Parameter
Description
Format
Example
country
Country filter
ISO 3166-1 alpha-2, lowercase
country-us, country-gb
region
Region or state
Name with underscores for spaces
region-california, region-new_york
city
City
Name with underscores for spaces
city-los_angeles, city-austin
isp
Internet service provider
Name with underscores for spaces
isp-comcast, isp-verizon_wireless
asn
Autonomous system number
ASN number
asn-7922
zip
Postal / zip code
Zip code
zip-90210
Use country-any if you want the full global pool without geographic filtering. You need at least one targeting parameter in every request.You can combine multiple filters. For example, to target Comcast subscribers in Los Angeles:
The more specific your targeting, the smaller the eligible pool. If you target a small city with a specific ISP, there may be fewer available nodes, which can affect speed and availability. Start broad and narrow down as needed.
Rotation rules control when the system replaces the current node during a session. Without a rotation rule, the session keeps the same node until it expires or encounters an error.
Parameter
Description
Example
Max
rotate-timed_N
Replace the node after N seconds (accepts s, m, h suffixes)
Rotation rules require a session. Without a session parameter, every request already gets a new node, so rotation doesn’t apply.Example: rotate IP every 5 minutes within a session:
Timed rotation doesn’t interrupt requests that are already in progress. If a request is running when the timer expires, it finishes on the current node. The next request gets a new node.
Error handling rules define what happens when a node fails during a session (goes offline, connection refused, timeout). These apply to infrastructure-level failures only. Target website responses (HTTP status codes like 403 or 429) are not visible to the proxy for HTTPS traffic and aren’t handled by these rules.
Parameter
Description
onerror-replace
Get a new eligible node. This is the default.
onerror-retry_N
Retry the request up to N times on the same node, then replace. Maximum N is 10.
onerror-fail
Return the error to your client. No retry, no replacement.
Example: retry 3 times on the same node before replacing:
Routing preferences affect which node the system picks when selecting or replacing a node. They influence preference, not eligibility. Filtering parameters decide which nodes are eligible; routing preferences decide which eligible node is chosen.
Parameter
Description
prefer-lookalike
When the system needs to select a new node (on rotation, error replacement, or initial allocation), prefer a node with similar characteristics to the previous one (same region, ISP, etc.).
This is useful when you want IP changes to be gradual rather than random. For example, if your session was using a Comcast IP in California and the node goes offline, prefer-lookalike tells the system to look for another Comcast IP in California before falling back to any eligible node.In the dashboard, this is the Prefer lookalike toggle in the Quick Connect (proxy generator) panel.Example:
By default, sessions can replace their node when rotation or error handling rules allow it. If you need strict binding to a single node with no automatic replacement, use bind-node.
Parameter
Description
bind-node
Lock the session to a single node. If the node fails, requests fail immediately instead of replacing.
When bind-node is active:
The session is locked to the node assigned on the first request.
Rotation rules are ignored.
If the node fails, you get an error (503 BOUND_NODE_FAILED) instead of a replacement.
You can combine it with onerror-retry_N to retry on the same node before failing.
To explicitly request residential nodes, use network-res. This is the default when no network parameter is provided, so you don’t need to include it unless your proxy package has both residential and mobile enabled and you want to restrict to residential only.
Parameter
Description
Values
network
Network type filter
res (residential), mob (mobile), res_mob (both), any (weighted)
Here’s every parameter available for residential proxies via Quick Connect:
Parameter
Description
Values
Default
Requires session
country
Country filter
ISO 3166-1 alpha-2 (lowercase), any
any
No
region
Region/state filter
Name (underscores for spaces)
any
No
city
City filter
Name (underscores for spaces)
any
No
isp
ISP filter
Name (underscores for spaces)
any
No
asn
ASN filter
ASN number
any
No
zip
Postal / zip filter
Zip code
any
No
network
Network type
res, mob, any, or combined (e.g. res_mob)
res
No
session
Session identifier
Letters, digits, underscores. Max 32 chars.
(none, rotating)
No
rotate-timed_N
Rotate after N (s/m/h suffix)
Up to 1 week
(keep node)
Yes
rotate-requests_N
Rotate after N requests
Up to 1,000,000
(keep node)
Yes
onerror
Error handling
replace, retry_N (max 10), fail
replace
Yes
prefer
Routing preference
lookalike
(none)
Yes
bind-node
Lock to single node
Flag (no value)
off
Yes
Connection string format:
{rules}:{package_key}@proxy.soax.com:1337
Rules are separated by hyphens. Multi-word values use underscores. Rules can appear in any order.If you’re passing rules in the subdomain for IP Auth over HTTPS, watch the 63-character DNS label limit. Use the shortcut forms in the table below (for example, c-us-ci-new_york-s-job1 instead of country-us-city-new_york-session-job1) if your config is too long.
To keep a connection string short — most often to stay under the 63-character DNS label limit with IP Auth over HTTPS — you can use the short form of each parameter name. The long and short forms are interchangeable and can be mixed in the same string.
Parameter
Shortcut
country
c
region
r
city
ci
isp
i
asn
a
zip
z
network
n
session
s
subaccount
sa
onerror
oe
For example, c-us-ci-new_york-s-job1 is equivalent to country-us-city-new_york-session-job1.
