Skip to main content
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.

​
How residential routing works

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.

​
Session types

There are two ways to use residential proxies: rotating (new IP every request) and sessions (keep the same IP across multiple requests).

​
Rotating (no session)

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.
Each time you run this, you’ll get a different IP.

​
Ephemeral sessions (held IP)

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.

​
Geo-targeting

You can target residential nodes by country, region, city, ISP, or ASN. These parameters filter which nodes are eligible for your requests. 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

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. 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

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. Example: retry 3 times on the same node before replacing:

​
Routing preferences

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. 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:

​
Node binding

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. 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.
  • Requires a session parameter.
Example:

​
Network type parameter

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.

​
Full parameter reference

Here’s every parameter available for residential proxies via Quick Connect: Connection string format:
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.

​
Parameter shortcuts

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. For example, c-us-ci-new_york-s-job1 is equivalent to country-us-city-new_york-session-job1.

​
Example configurations

Basic rotating proxy, US:
Session, UK, 5-minute rotation:
Session with retry on error, then replace with lookalike:
Specific city and ISP, mobile network:
Locked to a single node (no replacement on failure):

​
Limits

​
Next steps

Mobile proxies

Full reference for mobile proxy configuration.

Authentication

How to authenticate with username/password or IP Auth.

Error codes

Full list of SOAX error codes with causes and fixes.

Python examples

Working Python code for residential proxies.