> ## Documentation Index
> Fetch the complete documentation index at: https://developers.soax.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Residential Proxies
> 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.
## 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.
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
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.
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us-session-job1:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
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.
| 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:
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us-city-los_angeles-isp-comcast:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
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.
| Parameter | Description | Example | Max |
| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------- | --------- |
| `rotate-timed_N` | Replace the node after N seconds (accepts `s`, `m`, `h` suffixes) | `rotate-timed_300` (every 5 minutes), `rotate-timed_5m` | 1 week |
| `rotate-requests_N` | Replace the node after N requests | `rotate-requests_50` (every 50 requests) | 1,000,000 |
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:**
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us-session-scrape1-rotate-timed_300:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
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.
| 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:**
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us-session-job1-onerror-retry_3:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
## 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.
| 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:**
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us-session-job1-onerror-replace-prefer-lookalike:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
## 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`.
| 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.
* Requires a `session` parameter.
**Example:**
```bash theme={null}
curl -x proxy.soax.com:1337 -U "country-us-session-locked1-bind-node:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```
## 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.
| Parameter | Description | Values |
| --------- | ------------------- | ----------------------------------------------------------------------- |
| `network` | Network type filter | `res` (residential), `mob` (mobile), `res_mob` (both), `any` (weighted) |
## Full parameter reference
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.
### 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.
| 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`.
## Example configurations
**Basic rotating proxy, US:**
```
country-us:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```
**Session, UK, 5-minute rotation:**
```
country-gb-session-uk1-rotate-timed_300:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```
**Session with retry on error, then replace with lookalike:**
```
country-us-session-scrape1-onerror-retry_3-prefer-lookalike:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```
**Specific city and ISP, mobile network:**
```
network-mob-country-us-city-new_york-session-m1:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```
**Locked to a single node (no replacement on failure):**
```
country-us-session-locked1-bind-node:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```
## Limits
| Constraint | Value |
| ------------------------------------ | ---------------------------- |
| Session ID max length | 32 characters |
| Session ID characters | Letters, digits, underscores |
| Ephemeral session inactivity timeout | 60 seconds |
| Concurrent sessions | Package-dependent |
| RPS limit | Package-dependent |
| Concurrent connections | Package-dependent |
| `rotate-timed_N` max | 1 week |
| `rotate-requests_N` max | 1,000,000 |
| `onerror-retry_N` max | 10 |
| DNS label limit (IP Auth over HTTPS) | 63 characters |
## Next steps
Full reference for mobile proxy configuration.
How to authenticate with username/password or IP Auth.
Full list of SOAX error codes with causes and fixes.
Working Python code for residential proxies.