Skip to content

Sessions

Get a fresh exit on every connection, or hold one IP for up to thirty minutes with a session ID you choose.

Rotating

With no session parameter in the username, every new connection to the gateway gets a fresh pick from the upstreams that match your targeting. On residential that is usually a new IP; on ISP and datacenter it is one of the IPs allocated to you. This is the default and the right choice for most crawling: a block on one IP usually does not affect the next connection.

# Three connections, a fresh pick each time
for i in 1 2 3; do
  curl -s -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr:PASSWORD" https://ipinfo.io/ip
done

One thing to keep in mind: rotation is per connection, not per HTTP request. Over HTTPS your client opens a CONNECT tunnel and may send several requests through it with keep-alive; all of them share the tunnel's IP. Close the connection, or disable keep-alive, to force a fresh pick. Plain http:// requests are always one per connection: the gateway closes the connection after the response, so each one gets a fresh pick.

Sticky

Add session-ID to the username and the gateway pins that ID to one exit IP. Every connection that reuses the ID goes out through the same IP until the session ends. Use it for anything stateful: logging in to a Korean platform, adding to a basket on a marketplace, paging through results a site ties to the visitor's IP.

# Three requests, one IP, held for up to 15 minutes
for i in 1 2 3; do
  curl -s -x icn-01.gw.scalardata.ai:7777 \
    -U "k7f3q2-acme-country-kr-session-order77-sessduration-15:PASSWORD" \
    https://ipinfo.io/ip
done

A session lasts up to 30 minutes. Set the length with sessduration-MIN, from 1 to 30; without it the proxy user's default applies, or 10 minutes when it has none. The clock starts on the first connection that uses the ID, not on each request. When the session ends, the next connection with the same ID gets a fresh pick and a new clock, so an ID can be reused indefinitely.

If you need the same IP for hours or days, a sticky session is the wrong tool. ISP addresses stay allocated to your account for as long as the subscription is live; connections rotate among them, and a session holds one for up to 30 minutes. Choosing one specific IP is not available yet.

How session IDs work

You choose the ID; the gateway does not issue them. Any string of letters and digits works. IDs are scoped to the proxy user, the network and the targeting parameters they were first used with, which means:

  • The same ID on two different proxy users is two different sessions.
  • Changing any targeting parameter alongside an existing ID starts a new session, because the pinned IP may not satisfy the new targeting.
  • Different IDs are independent picks and can land on the same exit, especially on ISP or datacenter where your pool is the IPs allocated to you. Give each worker its own ID to spread them out.
# Two independent sessions running side by side
k7f3q2-acme-country-kr-session-worker1
k7f3q2-acme-country-kr-session-worker2

Sessions have no limit of their own, but their connections count toward the connection limits (see Errors, 429). Sessions are not billed separately.

When the IP goes away

If the upstream behind a session is taken out of service or fails a new connection, the gateway pins the session to another upstream that matches the same targeting, keeping the same deadline, and retries a failed connection once there. From then on the session goes out from a different address than the one before it. A connection that breaks mid-transfer is not retried.

For most work that is fine. For a logged-in flow, a site may treat the change of address as a new visitor and ask you to sign in again. If that matters to you:

  • Treat a login prompt or a reset cookie mid-session the way you would on a flaky home connection: start a new session ID and authenticate again.
  • Keep sessions short. The longer an IP is held, the more likely it drops.
  • Move the stateful part of the job to ISP or datacenter IPs, which stay allocated to you; hold one with a session ID.

A session is also released early if you stop using it: an ID that has had no connections for 5 minutes does not keep its IP reserved. Reusing the ID after that behaves like a fresh session.