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

# curl

> Working curl commands for SOAX residential and mobile proxies. Covers rotating and sessions with copy-paste examples.

curl is the quickest way to test SOAX from your terminal. Every example on this page is a single command you can copy, paste, and run immediately.

Replace `YOUR_PACKAGE_KEY` with your actual package key from the [dashboard](https://platform.soax.com).

## Residential proxies

### Rotating (new IP every request)

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

Run this multiple times and you'll get a different IP each time.

### Target a specific city

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

### Session (same IP across requests)

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

Run this multiple times with the same session ID and you'll see the same IP, as long as the session is active. Ephemeral sessions expire after 60 seconds of inactivity.

### Session with timed rotation

Rotate to a new IP every 5 minutes:

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

### Session with request-based rotation

Rotate to a new IP every 10 requests:

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

### Session with error handling

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

Replace with a similar node on error:

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

Fail immediately on error (no retry, no replacement):

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

## Mobile proxies

Mobile proxies use the same format. Add `network-mob` to your parameters.

### Rotating

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

### Session

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

### Target a specific carrier

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

### Mobile session with timed rotation

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

## IP Auth (HTTPS)

If you've added your IP to the allowlist in the dashboard, you can connect without credentials. Rules go in the subdomain instead.

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

With a session:

```bash theme={null}
curl --proxy "https://country-us-session-job1.proxy.soax.com:1337" https://checker.soax.com/api/ipinfo
```

<Warning>
  IP Auth via subdomain is limited to 63 characters (the DNS label limit). For complex rule combinations, use the [parameter shortcuts](/proxies/residential#parameter-shortcuts) (e.g. `c-us-ci-new_york-s-job1`) or switch to username/password authentication.
</Warning>

## SOCKS5

To connect via SOCKS5 instead of HTTP, use `--socks5`:

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

## Expected response

All examples above return a JSON response from the SOAX checker:

```json theme={null}
{
  "status": true,
  "data": {
    "ip": "185.123.45.67",
    "country_code": "US",
    "country_name": "United States",
    "region": "California",
    "city": "Los Angeles",
    "isp": "Spectrum",
    "carrier": ""
  }
}
```

The `ip` should be different from your real IP. If you targeted a specific country, the `country_code` should match.

## Next steps

<CardGroup cols={2}>
  <Card title="Python examples" icon="code" href="/examples/python">
    Working Python code for SOAX proxies.
  </Card>

  <Card title="Node.js examples" icon="code" href="/examples/nodejs">
    Working Node.js code for SOAX proxies.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/troubleshooting/error-codes">
    What to do when something goes wrong.
  </Card>

  <Card title="Residential proxies" icon="wifi" href="/proxies/residential">
    Full parameter reference.
  </Card>
</CardGroup>