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

# Mobile Proxies

> Full reference for SOAX mobile proxies. Covers how mobile routing works, session types, geo-targeting, connection parameters, and limits.

Mobile proxies route your traffic through real mobile carrier connections on 3G, 4G, and 5G networks. The IPs come from carriers like Verizon, AT\&T, Deutsche Telekom, and others worldwide.

SOAX's mobile pool includes over 30 million IPs from carriers across 195+ countries.

## How mobile proxies are different

Mobile proxies use the same parameter system, session model, and connection format as [residential proxies](/proxies/residential). The difference is where the traffic exits.

With residential proxies, your requests go through home WiFi connections. With mobile proxies, they go through cellular carrier connections. This matters because:

**Mobile IPs are naturally shared.** Carriers use NAT (network address translation) to share IP addresses across many subscribers. This means websites can't easily block a mobile IP without risking blocking thousands of real users. As a result, mobile IPs tend to have lower detection and block rates than residential IPs on heavily protected targets.

**Some content is mobile-specific.** Certain websites and apps serve different content, pricing, or ads to mobile users. Mobile proxies let you see exactly what a mobile visitor would see.

**Carrier metadata is different.** Mobile IPs carry carrier and network type information (3G/4G/5G) rather than home ISP information. This can be relevant for ad verification, app testing, or any workflow where the connection type matters to the target.

## When to use mobile proxies

Mobile proxies are the right choice when:

* Your target site aggressively blocks residential IPs but is more lenient with mobile traffic.
* You need to verify mobile ads, app content, or carrier-specific behavior.
* You're working with social media platforms that scrutinize connection types.
* You need the lowest possible detection rate and are willing to work with a smaller pool.

For general-purpose scraping, residential proxies are a good starting point. If you're hitting high block rates on specific targets, switching to mobile is worth testing.

## Session types

Session behavior is identical to residential proxies. You can use **rotating** (new IP every request) or **ephemeral sessions** (same IP across multiple requests).

### Rotating (no session)

Every request gets a new mobile node. No state between requests.

```bash theme={null}
curl -x proxy.soax.com:1337 -U "network-mob-country-us:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

### Ephemeral sessions (held IP)

Include a `session` parameter to bind to a node and reuse the same IP across requests.

```bash theme={null}
curl -x proxy.soax.com:1337 -U "network-mob-country-us-session-mobile1:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

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

Geo-targeting works the same way as residential. You can filter by country, region, city, carrier (using the `isp` parameter), ASN, or zip code.

| Parameter | Description              | Format                           | Example                                |
| --------- | ------------------------ | -------------------------------- | -------------------------------------- |
| `country` | Country filter           | ISO 3166-1 alpha-2, lowercase    | `country-us`, `country-de`             |
| `region`  | Region or state          | Name with underscores for spaces | `region-california`, `region-bavaria`  |
| `city`    | City                     | Name with underscores for spaces | `city-new_york`, `city-berlin`         |
| `isp`     | Mobile carrier           | Name with underscores for spaces | `isp-verizon_wireless`, `isp-t_mobile` |
| `asn`     | Autonomous system number | ASN number                       | `asn-6167`                             |
| `zip`     | Postal / zip code        | Zip code                         | `zip-10001`                            |

Use `country-any` if you want the full global pool without geographic filtering.

**Example: target T-Mobile subscribers in New York:**

```bash theme={null}
curl -x proxy.soax.com:1337 -U "network-mob-country-us-city-new_york-isp-t_mobile:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

<Warning>
  The mobile pool is smaller than the residential pool (30M vs 155M). Very specific targeting (small city + specific carrier) may result in fewer available nodes. If you get `502 NODE_NOT_FOUND` errors, try broadening your filters.
</Warning>

## Rotation rules

Rotation rules control when the system replaces the current node during a session. These work identically to residential.

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

**Example: rotate mobile IP every 10 minutes:**

```bash theme={null}
curl -x proxy.soax.com:1337 -U "network-mob-country-us-session-m1-rotate-timed_600:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

<Tip>
  Timed rotation doesn't interrupt requests that are already in progress. The current request finishes on the current node. The next request gets a new node.
</Tip>

## Error handling

Error handling rules define what happens when a node fails during a session. These apply to infrastructure-level failures only (node offline, connection refused, timeout). Target website responses (HTTP status codes) are not visible to the proxy for HTTPS traffic.

| 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 twice, then replace:**

```bash theme={null}
curl -x proxy.soax.com:1337 -U "network-mob-country-us-session-m1-onerror-retry_2:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

## Routing preferences

Routing preferences affect which node the system picks when it needs to select or replace a node.

| Parameter          | Description                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `prefer-lookalike` | Prefer a node with similar characteristics to the previous one (same carrier, region, etc.). |

This is useful when you want IP changes to feel gradual. If your session was using a Verizon IP in Texas and the node goes offline, `prefer-lookalike` tells the system to look for another Verizon IP in Texas before falling back to any eligible mobile 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 "network-mob-country-us-session-m1-onerror-replace-prefer-lookalike:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

## Node binding

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 "network-mob-country-us-session-locked1-bind-node:YOUR_PACKAGE_KEY" https://checker.soax.com/api/ipinfo
```

## Network type parameter

To request mobile nodes, include `network-mob` in your connection string. If your proxy package has both residential and mobile enabled and you don't specify a network type, the default is `res` (residential). To use mobile, you need to set it explicitly.

| Parameter | Description         | Values                                                                  |
| --------- | ------------------- | ----------------------------------------------------------------------- |
| `network` | Network type filter | `res` (residential), `mob` (mobile), `res_mob` (both), `any` (weighted) |

## Full parameter reference

Every parameter available for mobile 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`               | Carrier 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.

## Example configurations

**Basic rotating proxy, US mobile:**

```
network-mob-country-us:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```

**Session, German mobile, 10-minute rotation:**

```
network-mob-country-de-session-de1-rotate-timed_600:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```

**Session with retry on error, then replace with lookalike:**

```
network-mob-country-us-session-m1-onerror-retry_3-prefer-lookalike:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```

**Specific carrier and city:**

```
network-mob-country-us-city-los_angeles-isp-verizon_wireless-session-v1:YOUR_PACKAGE_KEY@proxy.soax.com:1337
```

**Locked to a single mobile node:**

```
network-mob-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                |

## Residential vs mobile: quick comparison

|                      | Residential                             | Mobile                                                     |
| -------------------- | --------------------------------------- | ---------------------------------------------------------- |
| IP source            | Home ISP connections                    | Mobile carrier connections (3G/4G/5G)                      |
| Pool size            | 155M+                                   | 30M+                                                       |
| Detection risk       | Low                                     | Very low                                                   |
| Best for             | General scraping, price monitoring, SEO | Mobile content, ad verification, heavily protected targets |
| Default network type | Yes (`res`)                             | No (must specify `network-mob`)                            |
| Credit cost per tier | Same                                    | Same                                                       |
| Parameter system     | Identical                               | Identical                                                  |

## Next steps

<CardGroup cols={2}>
  <Card title="Residential proxies" icon="wifi" href="/proxies/residential">
    Full reference for residential proxy configuration.
  </Card>

  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    How to authenticate with username/password or IP Auth.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/troubleshooting/error-codes">
    Full list of SOAX error codes with causes and fixes.
  </Card>

  <Card title="Python examples" icon="code" href="/examples/python">
    Working Python code for mobile proxies.
  </Card>
</CardGroup>