Rotating proxy parameters

Choose the exit country and keep the same IP with sticky sessions by adding parameters to the rotating proxy password.

These parameters apply only to rotating residential proxies. The Gateway endpoint card in the dashboard builds them for you when you set Exit country and IP mode. Use this page when you build credentials in code.

Parameters go in the password, not the username

Keep the username exactly as shown in the dashboard. Add parameters to the end of the password. Credentials in any other shape are rejected with 407 Proxy Authentication Required.

Format

username: USERNAME
password: PASSWORD[_country-CC][_session-NNNNNNNN_ttl-T]

Parameter	Value	Effect
`_country-CC`	Uppercase two-letter country code, for example `US`, `JP`, `DE`	Exit through IPs in that country. Omit it to use the global pool.
`_session-NNNNNNNN`	Exactly 8 digits	Keep the same exit IP for every connection that uses this ID.
`_ttl-T`	`5`, `10`, `15`, or `30` (minutes)	How long the sticky session lasts. Required with `_session`, not allowed without it.

Use only the countries listed in the dashboard's Exit country menu.

Examples

Goal	Password
Rotate across the global pool	`PASSWORD`
Rotate within the United States	`PASSWORD_country-US`
Keep one Japanese IP for 10 minutes	`PASSWORD_country-JP_session-48213907_ttl-10`
Keep one IP from any country for 30 minutes	`PASSWORD_session-77310452_ttl-30`

As a proxy URL:

curl -x "http://USERNAME:PASSWORD_country-US_session-48213907_ttl-10@HOST:PORT" https://ipinfo.io/json

How rotation works

Without _session, the gateway picks a new exit IP for each new proxy connection. HTTPS requests travel through a tunnel, and every request sent through the same tunnel uses the same IP. Clients that reuse connections (keep-alive, requests.Session, browser connection pools) therefore keep one IP until the connection closes.

This is what Rotate on every request in the dashboard means. To get a new IP for each request, open a new connection for each request or give each request a different session ID.

Sticky sessions

Connections that use the same session ID during its TTL leave through the same IP. Use this for logins, checkouts, and other multi-step flows.

To switch IPs, generate a new session ID.
A residential IP can go offline before the TTL ends. Your session then moves to a different IP.
30 minutes is the maximum. If you need one IP for days or weeks, use a static ISP proxy instead.

Generate session IDs in code:

import random

def rotating_password(base_password, country=None, ttl_minutes=None):
    password = base_password
    if country:
        password += f"_country-{country.upper()}"
    if ttl_minutes:
        assert ttl_minutes in (5, 10, 15, 30)
        session_id = f"{random.randrange(100_000_000):08d}"
        password += f"_session-{session_id}_ttl-{ttl_minutes}"
    return password

print(rotating_password("PASSWORD", country="us", ttl_minutes=10))
# e.g. PASSWORD_country-US_session-04821390_ttl-10

function rotatingPassword(basePassword, { country, ttlMinutes } = {}) {
  let password = basePassword;
  if (country) password += `_country-${country.toUpperCase()}`;
  if (ttlMinutes) {
    if (![5, 10, 15, 30].includes(ttlMinutes)) throw new Error('Invalid TTL');
    const sessionId = String(Math.floor(Math.random() * 1e8)).padStart(8, '0');
    password += `_session-${sessionId}_ttl-${ttlMinutes}`;
  }
  return password;
}

Common mistakes

Wrong	Right	Why
`USERNAME_country-US` as the username	`PASSWORD_country-US` as the password	Parameters are read from the password only.
`_country-us`	`_country-US`	Country codes must be uppercase.
`_session-demo`, `_session-abc123`	`_session-12345678`	Session IDs are exactly 8 digits.
`_session-12345678_ttl-60`	`_ttl-30` or less	TTL is 5, 10, 15, or 30.
`PASSWORD_ttl-10`	`PASSWORD_session-12345678_ttl-10`	TTL needs a session.
`PASSWORD_session-12345678_ttl-10_country-US`	`PASSWORD_country-US_session-12345678_ttl-10`	The country comes before the session.
`-cc-US`, `-sessid-`, `zone-`	`_country-US`, `_session-`	Other providers' syntax is not supported.

Static ISP proxies

Static ISP proxies take no parameters. Use the password exactly as shown. Adding a suffix causes 407. The IP stays the same for the whole order. If an IP has a problem, request a replacement from the dashboard's Help page.