> ## Documentation Index
> Fetch the complete documentation index at: https://www.illusory.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Choose between rotating IPs and sticky sessions that hold the same IP.

Residential proxies support two modes, chosen by whether you include a `-session-` token in your username.

## Concurrency

There is no connection limit. Everything runs over a single endpoint (`proxy.illusory.io:1080`), so you can open as many simultaneous connections as you need. You never generate or manage a proxy list: point every browser, worker, or thread at the same proxy URL and each connection picks up its own residential IP automatically.

## Rotating (default)

Omit `-session-` and **every request gets a fresh residential IP**. This is ideal for high-volume scraping, spreading requests across many IPs, and avoiding rate limits.

```bash theme={null}
# A new exit IP on each request
curl -x "http://USERNAME-country-us:SECRET@proxy.illusory.io:1080" https://api.ipify.org
```

## Sticky

Add `-session-<id>` and **all requests with the same id keep the same exit IP**. Use this when a site needs continuity: logins, carts, checkouts, multi-step flows.

```bash theme={null}
# Both requests exit from the same IP
curl -x "http://USERNAME-country-us-session-checkout1:SECRET@proxy.illusory.io:1080" https://api.ipify.org
curl -x "http://USERNAME-country-us-session-checkout1:SECRET@proxy.illusory.io:1080" https://api.ipify.org
```

* Pick any id you like (`checkout1`, `user42`, a UUID…). Different ids get different IPs.
* Your session ids are private to your account. Two customers using the same id never share an IP.

## Sticky duration

By default a sticky session holds its IP for a standard window. Control it with `-sesstime-<min>` (minutes, **5-1440**):

```bash theme={null}
# Hold the same IP for ~30 minutes
curl -x "http://USERNAME-country-us-session-checkout1-sesstime-30:SECRET@proxy.illusory.io:1080" https://api.ipify.org
```

After the duration elapses, the session rotates to a new IP. Values are clamped to the 5-1440 minute range.

## Refreshing IPs and building a list

You do not maintain a list of proxies. The one endpoint hands out IPs based on how you build the username.

### Rotating: refresh by reconnecting

With no `-session-` token, every new connection exits a fresh residential IP and rotates on each new request or refresh. "Refreshing" an IP just means opening a new connection. Run many connections in parallel and each one exits a different IP, with nothing to manage on your side.

### Sticky: build a stable set of IPs

A single `-session-<id>` holds one IP. To hold a stable *set* of IPs, use different session ids: each distinct id pins its own IP, so N ids give you N persistent proxies. Session ids are arbitrary, so name them however you like (`amazon1`, `amazon2`, `amazon3`, a UUID, and so on).

```bash theme={null}
# Three distinct session ids hold three separate IPs
curl -x "http://USERNAME-country-us-session-amazon1:SECRET@proxy.illusory.io:1080" https://api.ipify.org   # IP #1
curl -x "http://USERNAME-country-us-session-amazon2:SECRET@proxy.illusory.io:1080" https://api.ipify.org   # IP #2
curl -x "http://USERNAME-country-us-session-amazon3:SECRET@proxy.illusory.io:1080" https://api.ipify.org   # IP #3
```

To rotate one of these IPs, change its session id (or drop the `-session-` token entirely for full rotation). A sticky IP can be held for up to 24 hours (1440 minutes) with `-sesstime-<min>`.

In short: rotating plus parallel connections gives you many IPs with zero management (best for scraping), while sticky sessions with distinct ids give you a stable list of N proxies. Both run over the one endpoint with unlimited concurrency.

## Choosing a mode

| Use case                               | Mode     |
| -------------------------------------- | -------- |
| Large-scale scraping / data collection | Rotating |
| Login → action → logout flows          | Sticky   |
| Checkout / cart continuity             | Sticky   |
| Maximizing IP diversity                | Rotating |

<Note>
  A sticky session pins one residential peer for its lifetime. If that peer is slow, start a new session id or switch to rotating.
</Note>