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.
curlopens 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.