Try 25 MB of US mobile proxy data free for 30 days.Start free trial

Getting started

Rotating vs sticky sessions

How exit IPs are assigned per connection, when they change, and how the _sticky suffix keeps one for anywhere from 10 seconds to 30 minutes.

The session mode is chosen per request by a suffix on the username, so one credential can be used both ways at the same time.

Rotating

With no suffix, each new connection to the proxy gets a new exit IP:

mlabs_a1f9c3:<PASSWORD>@proxy.masklabs.io:8080

An exit IP is assigned when a connection to the proxy is opened, and it stays with that connection for as long as it is open. For HTTPS this means one IP per tunnel: the client opens a CONNECT tunnel to the target, and every request sent through that tunnel leaves from the same IP. The IP changes when the next tunnel is opened.

So "a new IP on every request" depends on your client opening a new connection for every request. Most HTTP clients and every browser reuse connections by default (keep-alive, connection pooling), and requests that share a connection share an exit IP. To rotate on every request, make the client open a new connection each time:

  • Disable keep-alive or connection pooling, or create a new client or session per request.
  • In a browser, a normal reload reuses the open connection and keeps the IP. Close the tab or start a new browser context to get a new one.
  • curl opens a new connection per invocation, so running the same command twice gives two IPs.

If your client reuses connections and you want each connection to keep its IP, that is already how it works. If you want the same IP across connections, use a sticky session.

Sticky

Append _sticky to keep the same exit IP for 5 minutes, across connections:

mlabs_a1f9c3_sticky:<PASSWORD>@proxy.masklabs.io:8080

Every connection made with that login during the window uses the same exit. When the window ends, the next connection picks a new exit and starts a new window.

Window length

To change how long the IP is kept, add the length after _sticky, in seconds (s) or minutes (m). This keeps it for 90 seconds:

mlabs_a1f9c3_sticky_90s:<PASSWORD>@proxy.masklabs.io:8080

This keeps it for 6 minutes:

mlabs_a1f9c3_sticky_6m:<PASSWORD>@proxy.masklabs.io:8080

The window can be any whole number of seconds or minutes from 10 seconds to 30 minutes. Use one unit: _sticky_1m30s is not valid, so write _sticky_90s. Values outside the range are clamped, so _sticky_5s gets 10 seconds and _sticky_45m gets 30 minutes. With no length, _sticky keeps the IP for 5 minutes, the same as _sticky_5m or _sticky_300s.

The window starts at the first connection and later connections don't extend it. A _sticky_45s login gets a new exit 45 seconds after it first connected, however many requests it sent in between.

A credential has one sticky session at a time, and the window is set when the session starts. If a 5-minute session is running, a _sticky_45s connection joins it and keeps that IP until the 5 minutes are up. The endpoint builder in the dashboard has a Window field that writes the suffix for you.

To switch IPs before the window ends, click Rotate IP on the credential's page in the dashboard, or call rotate-ip in the API. The next _sticky connection gets a new IP. Connections that are already open keep theirs. Rotating connections don't need this, since they get a new IP every time.

If the exit fails

If the exit a sticky session is using goes down or stops answering, the session moves to another exit in the same location. The exit IP changes and the location does not. The session keeps the new exit for the rest of the window, and the window does not restart.

Think of it like losing cell service while driving through a tunnel. Your phone picks up a different tower on the other side, but you're still in the same area. The exit that went down can't carry traffic, so the choice is a different exit nearby or a failed connection.

Combining with location

Location suffixes work with either mode:

mlabs_a1f9c3_loc_ORD_sticky:<PASSWORD>@proxy.masklabs.io:8080
mlabs_a1f9c3_loc_LAX_sticky_45s:<PASSWORD>@proxy.masklabs.io:8080

The suffixes can go in any order. See Location targeting for the location codes.