Sticky sessions — Docs

What sticky sessions are

By default rotating pools hand out a new exit IP per request — that's the whole point of rotation. Sticky sessions opt out for a defined window: all requests carrying the same session token route through the same IP for as long as the session is alive.

We do not rent the IP to you. The pool keeps owning it. We just promise affinity for that token, in that pool, for the session lifetime.

Token syntax

Append -session-TOKEN to the username. The token is opaque to us — pick anything; 8 to 16 alphanumeric characters is the convention.

shell

# Username:  cust_2c4f9a-session-CART42
$ curl -x http://cust_2c4f9a-session-CART42:[email protected]:8080 \
       https://target.com/login

# Same token, same IP for as long as the session lives:
$ curl -x http://cust_2c4f9a-session-CART42:[email protected]:8080 \
       https://target.com/cart

Two clients using the same token get the same IP — that's by design, for cases where multiple workers in a fleet share session state.

Lifetime and what extends it

Default lifetime: 10 minutes from the first request that carries the token.
Renewal: every request through the same token resets the inactivity timer. As long as you keep using the session, it stays alive (up to a hard cap of 60 minutes).
Custom lifetime: append a duration suffix — -session-CART42-30m for 30 minutes, -session-CART42-1h for one hour. The hard cap is one hour.

When the IP goes away anyway

Real residential IPs come and go — the underlying device may disconnect at any time. If the upstream IP drops mid-session, the next request through the token gets a fresh IP and a new session starts. This is normal.

When to use vs when to skip

Use sticky sessions for:

Login flows that bind cookies to the originating IP.
Multi-page cart / checkout where the target IP-pins the session.
Two-step signup or KYC-style flows where dropping the IP loses state.
Any sequence the target rate-limits per IP and you want to spend the limit on one IP.

Skip sticky sessions for:

Bulk parallel scraping where you want IP diversity.
Single-shot probes — there's nothing to share.
Per-request rate-limit avoidance — that's the opposite use-case; rotation is the answer.

Sticky session vs static IP

Both keep one IP across requests. The difference is duration and billing:

Sticky session — minutes, on a residential or mobile pool IP that the underlying user owns. Trust score is high. The IP cycles eventually.
Static IP — calendar months, on a datacenter IP that we rent to you exclusively for the period. Trust score is low–medium but the IP is rock-stable for as long as you pay for it.

See /products for the full comparison.

Forcing a new IP

Drop the session token (or change it). The next request, by definition, can no longer be affined and the gateway picks a fresh exit.

shell

# Step 1 — sticky to one IP
$ curl -x http://USER-session-A:[email protected]:8080 https://target.com/

# Step 2 — drop the token, get a fresh exit
$ curl -x http://USER:[email protected]:8080 https://target.com/

# Step 3 — different sticky token, different IP
$ curl -x http://USER-session-B:[email protected]:8080 https://target.com/