New: change proxy rules without touching your code

Say you run a three-month mobile ad campaign in five US cities. Every hour, a script checks each city the way a local mobile user would see it. Does the ad show up on the right pages? Does it link to the right landing page, and does that page show the local offer?

For three months, each city’s checks need the same setup: that city, a mobile network, and an IP that holds for the length of a check. A normal sticky session keeps that setup in the proxy username and expires after a set time. Campaigns also change while they run, and every change to the setup means a change to the script.

Today we launched Stateful Sessions to fix that. A Stateful Session stays until you delete it. It has a name, one connection string and a set of rules that we store for you. The exit IP can change over time, but the rules only change when you change them. Stateful Sessions are available for every SOAX account.

What keeps a session the same

• The session doesn’t expire. It keeps its name and connection string until you delete it.

• Its rules stay with it. Location, network type and rotation rule are stored with the session, and every new IP it gets follows them.

• You choose when the IP changes: only when the node fails, on a timer, after a set number of requests, or never while the node is online (pinned).

• You choose what happens when a node fails. The session can retry the same node, return the error to your client or switch to another node. When it switches, you can ask for a node similar to the last one.

• The dashboard shows each session’s current IP, its location and how long it has had that IP.

Example: three months of ad checks

Week 1: create one session per city

This creates the San Francisco session. It uses mobile IPs and keeps its exit node until the node fails. When it has to move, it prefers a node similar to the last one.

curl -X POST "https://api.platform.soax.com/v1/proxy/packages/$PKG/stateful-sessions" \
  -H "Authorization: Bearer $SOAX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ads-sf",
    "ruleset": {
      "country": "us",
      "region": "california",
      "city": "san_francisco",
      "network_type": "mobile",
      "rotation_trigger": "on-error",
      "lookalike": true
    }
  }'

Do the same for the other four cities. Each response includes the session’s exit IP and connection string, and your script sends each city’s checks through that city’s string:

curl -x "http://stateful-ads-sf:pkgKEY123@proxy.soax.com:5001" https://publisher.example/sports

Weeks 1 to 12: new IPs, same rules

Mobile devices go offline and come back. When the node behind ads-sf goes offline, the session moves to a similar mobile node in San Francisco, and the next check runs from there. Over three months, ads-sf may go through many IPs. Each of them is a mobile IP in San Francisco, and the script uses the same connection string throughout.

When a check fails, look the session up in the dashboard. It shows the IP the session had and since when, which tells you whether the ad broke or the session moved to a new node.

Week 5: the campaign adds a city

Create a sixth session and add its connection string to the script. The first five sessions keep running as they were.

Week 8: San Francisco also needs Wi-Fi checks

The client wants to see how the San Francisco ads look on home connections. Change the session’s network type in the dashboard, or with one API call:

curl -X PATCH "https://api.platform.soax.com/v1/proxy/packages/$PKG/stateful-sessions/$SID" \
  -H "Authorization: Bearer $SOAX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ruleset": {"network_type": "wifi"}}'

From the next check on, ads-sf exits on a Wi-Fi connection in San Francisco, with no change to the script.

Week 12: the campaign ends

Disable the sessions. They keep their names, ports and rules, so you can enable them again for the next campaign.

When the IP must not change

Some jobs break on any new IP, for example a long run that has to finish on one login. For those, pin the session: set rotation_trigger to bind and error_handling to retry_3. When a request fails, the session retries its node instead of moving to a new one.

A pin lasts as long as the node is online. Residential and mobile nodes can stay online for hours, but not indefinitely, and when a node leaves the network, no setting can keep its IP. Pinning suits a job of a few hours. For a job that runs for weeks, like the ad checks above, let the session move and keep its rules.

If you create a session without a rotation rule, it changes its IP every five minutes. Set the rule you need when you create the session.

Limits and pricing

• Sessions are free. You pay for traffic as usual.

• Each package allows up to 1,000 sessions by default. Contact support if you need more.

• You can rotate a session manually up to once per second.

• Timed rotation can run as often as every 10 seconds.

Get started

New to SOAX and want to try Stateful Sessions? Create a free account

Already a customer? Stateful Sessions are in your dashboard. Open the dashboard to create your first session, or read the API documentation.