Sessions and rotation

Choose a routing strategy for each new proxy connection: rotate among eligible exits, reuse a sticky session with failover, or reuse a fixed session without failover.

Choose a strategy

Goal	Username	Exit behavior
Independent connections	v1_rotate	Select an eligible exit each time a connection is opened
Prefer continuity and allow recovery	v1_sticky_session_job-42	Reuse the binding; permit rebinding if its exit is unreachable
Fail instead of changing a bound exit	v1_fixed_session_job-42	Reuse the binding; do not fail over an unreachable bound exit

Geographic filters can be appended to each strategy. Use a new session ID if you change a session’s strategy or filters.

HTTP and SOCKS5 use the same routing usernames and workspace-scoped session bindings. Changing proxy protocol does not independently create a new binding when the workspace, session ID, and routing policy stay the same.

Rotation happens at connection boundaries

v1_rotate_countries_US,GB

An exit is selected when a new proxy connection is dialed. Requests sent over an existing HTTP CONNECT or SOCKS5 tunnel continue using that tunnel’s exit.

An eligible exit may be selected again on a later connection. Rotation is not a promise of a unique IP, and it does not switch an established tunnel between exits.

If your client library pools or reuses tunnels, one tunnel may carry several destination requests. Close or replace the connection when you need another selection.

Sticky sessions

v1_sticky_session_checkout-42_countries_US

The first connection establishes a session binding. Later connections using the same workspace, session ID, strategy, and geographic policy reuse that binding while it remains active.

If the bound exit cannot be reached during connection setup, sticky routing can attempt to bind another eligible exit. The alternative must satisfy the same policy. A target website refusing a connection does not itself cause the session to rotate to another exit.

Failover applies when establishing a connection. An already established tunnel is not transparently moved or replayed after a failure.

Fixed sessions

v1_fixed_session_audit-42_regions_EU

Fixed routing refuses exit failover for an active binding. If its bound exit cannot be reached, the connection fails.

If the bound exit leaves the network, a still-active fixed binding cannot rebind: later connection setup with that ID fails. Start a new session ID to request another exit. HTTP and SOCKS5 report setup failures differently; see Troubleshooting.

Fixed describes the binding’s failover policy. It is not a dedicated-IP reservation or a permanent IP guarantee. Exit network addresses can change.

Session identity and policy

Session IDs are scoped to the workspace authenticated by the key. Different keys from the same workspace can therefore use the same session ID and binding. Different workspaces have separate session namespaces.

For independent workers, assign independent IDs:

v1_sticky_session_worker-01_countries_US
v1_sticky_session_worker-02_countries_US

Keep the exact policy stable for each ID, including list ordering. An active binding with a different strategy or policy can fail during connection setup. To request another policy or start a separate binding, choose a new session ID:

# Original policy
v1_sticky_session_job-42-us_countries_US

# New policy, with a new ID
v1_sticky_session_job-42-gb_countries_GB

Binding lifetime

Session bindings last a limited time set by the service. The username has no TTL or duration parameter, and sending traffic through a session does not guarantee that its binding stays. Do not treat a session ID as an indefinite IP reservation or rely on an open tunnel to preserve a binding for later connections.

Plan for a binding to end at any time. After it expires, a new connection may acquire another eligible exit even when it uses the same ID. Existing tunnel lifetime and session binding lifetime are separate concerns; see Protocols and limits.