Sticky sessions and rotation

Two modes: with session + time you get stickiness, without them you get rotation. This page is about what each one actually guarantees — the difference in wording decides whether your design works.

Sticky sessions

curl -x 'http://USERNAME-country-US-session-job1-time-30:PASSWORD@GATEWAY_HOST:58971' \
  https://api.ipify.org

Sessions and exit IPs

The same proxy account, session value and filters usually keep the same exit IP for the specified duration. Residential devices can go offline, so sticky sessions do not guarantee a permanently fixed IP.

The same session value with different operating systems uses separate sessions. For example, session-job1 with os-ios, os-windows, or no OS filter is treated as three separate sessions.

When a session starts

A session starts after the first successful proxy connection. If the first connection fails, the session has not started and you can retry later.

Session expiry and connection failures

After a session expires, the next new connection receives an exit IP matching the selected filters. The assigned IP may be the same as before.

If an active session is temporarily unavailable, the request returns an error: 503 service_unavailable for unavailability, 502 for connection failure, or 504 for a timeout. Retry with a limit or use a new session value to create a session. Existing TCP connections are not automatically closed when a session expires.

Session duration

time accepts 1–120 minutes. Choose a duration that covers your task; a process taking only a few minutes does not need a 120-minute session.

Rotation mode

Omitting session gives you rotation:

curl -x 'http://USERNAME-country-US:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org

Every new TCP connection receives an exit IP matching the selected filters. The assigned IP may repeat a previous result.

Forcing new connections

How to do it per language:

import requests

proxy = "http://USERNAME-country-US:PASSWORD@GATEWAY_HOST:58971"
proxies = {"http": proxy, "https": proxy}

# A fresh Session (and connection pool) each time
for _ in range(5):
    with requests.Session() as session:
        print(session.get("https://api.ipify.org",
                          proxies=proxies, timeout=30).text)

# Or disable keep-alive on one Session
headers = {"Connection": "close"}

Isolating concurrent work with distinct session values

To run several non-interfering sessions at once, give each one its own session value:

import concurrent.futures
import requests

def fetch(worker_id: int) -> str:
    user = f"USERNAME-country-US-session-w{worker_id}-time-30"
    proxy = f"http://{user}:PASSWORD@GATEWAY_HOST:58971"
    return requests.get(
        "https://api.ipify.org",
        proxies={"http": proxy, "https": proxy},
        timeout=30,
    ).text

with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
    for ip in pool.map(fetch, range(8)):
        print(ip)

Eight workers, eight independent sessions, each holding its own exit IP for 30 minutes.

Choosing between them