Stateful Sessions
Set your proxy rules once and keep them for as long as you need
Your settings are stored on our side, not in your scripts. One connection string uses them until you delete the session.
Trusted by fast-growing companies around the world.
Keep your proxy settings out of your scripts
Settings in the username
New connection string per setup
Setting changes mean code changes
Session ends when traffic stops
Exit IP unknown until first request
Stateful Sessions
One connection string, any setup
Change settings without touching code
Lasts until you delete it
Exit IP known before first request
How a Stateful Session works
Describe it once
Choose the location, network type, rotation and what happens when a node fails.
- profile_a1f3example.comprofile_7k29ebay.comprofile_3de1openmaps.ioprofile_f9c2citystats.io
Get the IP up front
We bind the session straight away, so you get the connection string and exit IP before you send any traffic.
Change it any time
Move a session from the US to Germany in the dashboard or API, and the next request follows.
Set it up with one API call
/v1/proxy/packages/{package_id}/stateful-sessions
{ "data": [ { "id": "6f1c2a9e-1b7d-4c1e-9a55-2f0d3b8e7c11", "name": "checkout", "status": "enabled", "ruleset": { "country": "us", "rotation_trigger": "bind", "error_handling": "retry_3" }, "exit_ip": "203.0.113.42", "country": "us", "city": "san_francisco", "bound_since": "2026-10-21T08:15:02Z", "connection_string": { "uri": "stateful-checkout:pkgKEY123@proxy.soax.com:5001" } } ], "failed": 0, "reason": null }
You set the rules for when the IP changes
The session and its settings stay the same. The exit IP changes when your rules say so, when you ask for a new one, or when the node goes offline.
Rotation rules
Pin the node, change it on error, on a timer from 10 seconds, or after a set number of requests.
Error handling
Retry the same node, return the error to your client, or move to another node.
Lookalike nodes
When a node has to change, prefer one with a similar location and ISP.
Rotate on demand
Ask for a new exit IP and get it in the same response, up to once per second.
Pause and resume
Disable a session and turn it back on later with the same name, port and rules.
See every session
Check each session's exit IP, location and how long it has held that IP.
Two ways to authenticate
Both methods work over HTTP, HTTPS and SOCKS5.
Username and password
The session name is the username and your package key is the password, on a shared port.
- HTTPHTTPSSOCKS5
IP allowlist
Add your server's IP to the allowlist and each session gets its own port, so your client sends no username or password.
Sessions are free. You only pay for traffic.
No charge per session
Creating, pausing and deleting sessions costs nothing. You pay for traffic at your plan's rate.
1,000 per package
Each package holds up to 1,000 sessions, and support can raise the limit.
Residential and mobile
Use either network, or both, at one rate.
Frequently asked questions
A Stateful Session is stored on our side and has no expiry timer. It keeps its name, connection string and rules until you delete it, and you can change the rules without changing your client. A session in the proxy username expires after 60 seconds without traffic, and its rules are fixed by the first request. To change them, you have to start a new session ID.
Yes. The session and its settings stay the same, but the exit IP can change. That happens when a rotation rule runs, when you rotate the session yourself, when a node fails and error_handling is replace, or when you change a rule the current node doesn't match. Residential and mobile nodes also go offline, and no setting can keep a node that has left the network.
Pin the session: set rotation_trigger to bind and error_handling to retry_3 or fail. It then stays on its current node and doesn't rotate on a timer or a request count. If the node goes offline, the session moves to a new exit IP after your error rule has run, so pinning suits a job of a few hours, not a month. If a similar IP is good enough, use on-error with lookalike: true instead.
The session changes its exit IP every five minutes (timed:300) and moves to another node when the current one fails. If you need the IP to stay longer, set rotation_trigger when you create the session. You can change the rule later, but you can't remove it.
On every plan you can choose the country, region, city and ISP, and use the residential network, the mobile network or both. ASN and ZIP targeting are on the Scale and Enterprise plans. Each setting takes one value, and a setting you leave empty matches any value.
Each package holds up to 1,000 sessions, and paused sessions count toward that limit. You can create up to 1,000 sessions with the same rules in one API request. Check the failed field in the response, because a batch can return fewer sessions than you asked for. Contact support if you need a higher limit.
Sessions are free. You pay for the traffic that goes through them at your plan's rate, and residential and mobile traffic cost the same. The rate also depends on the country of the exit IP. See pricing for the rates on each plan.
Both. In the dashboard you can create sessions, change their rules, rotate them, and see each session's exit IP, location, network and how long it has held that IP. The API does the same, and it can also create sessions in bulk and delete up to 100 at once.
Yes. Set the session's status to disabled: it stops carrying traffic but keeps its name, port, rules and connection string. When you turn it back on, we bind it to a node first. If we can't find a node for it at that moment, it stays paused. A paused session still counts toward your package limit and may come back on a different IP.