Rotating a Mobile Proxy IP From a Script: Link, API and Timer

A mobile proxy line keeps the same carrier address until something asks for a new one. On Mobile Proxies US that something can be a person clicking in the dashboard, a GET on the line's rotation link, a script that reads that link from the API, or a timer the line runs on its own. A script that rotates well treats the change as asynchronous: ask, wait, confirm, then continue. This page compares the programmatic triggers and shows the confirmation step, which is the part most integrations get wrong.

What a rotation actually does

The device holding the SIM drops its data session and re-attaches to the carrier. The carrier hands out a new address from the same regional pool. New address, same carrier, same metro. Any TCP connections open through the proxy at that moment are reset, which is why a rotation should be sequenced between jobs rather than fired during one.

The address is sticky by default. If nothing asks for a change, the carrier keeps it for as long as its own network keeps the session up, which is typically hours and often longer. There is no limit on how many rotations you make. What does exist is a wait between them: min_time_change_ip is the number of minutes the rotation link holds that line to, 0 meaning none, and phone lines also have their own short cooldown of 1 to 2 minutes.

Trigger one: the rotation link

Every line has a rotation_link, shown in the dashboard and returned by GET /proxies/my. It has the form /backend/api_v1/proxy/change-ip?license=UUID, or a short /c/TOKEN form, on a rotation host that can differ from the dashboard host. A plain GET rotates that line. No header, no key, no body. That makes it easy to paste into tools that only know how to hit a URL.

Typical homes for the link: a cron entry, a Zapier or n8n step, a Scrapy middleware, a shell alias. The licence uuid in the link is the credential, so treat it as a secret. Anyone holding it can rotate the line and read its status, though not its login: the status endpoint returns no credentials.

# shell
curl -s "$ROTATION_LINK"
# crontab: new address at the top of every hour
0 * * * * curl -fsS "$ROTATION_LINK" >/dev/null

Trigger two: a script driven by the API

A program that already talks to the API reads rotation_link and min_time_change_ip from GET /proxies/my, calls the link, then follows up on GET /proxy/status. Use this when the rotation is one step in a larger program; use the bare link when rotation is the whole program.

A refusal is HTTP 400 with a JSON message. Treat it as information, not failure: it says how long the line still has to wait. Do not retry a rotation that is still running. Wait for the new IP, then carry on.

import os, requests
BASE = "https://cp.mobileproxiesus.com/backend/api_v1"
H = {"x-api-key": os.environ["MPUS_API_KEY"]}
lines = requests.get(f"{BASE}/proxies/my", headers=H, timeout=15).json()["proxyList"]
line = next(l for l in lines if l["uuid"] == UUID)
r = requests.get(line["rotation_link"], timeout=30)
if r.status_code == 400:
    print("refused:", r.json()["message"])

Trigger three: the timer

A line can rotate itself on an interval with no call from you. Set it in the dashboard, or with POST /license/update-rotation-time and a body of uuid and minute. The minimum is 5 minutes; minute 0 switches it off. The timer is the right choice when the consumer of the proxy cannot easily call out, for example a browser profile in Undetectable.io or GoLogin, a phone, or a tool whose author never thought about rotation.

If your script needs full control over when the address changes, leave the timer off so the two do not interfere.

curl -s -X POST https://cp.mobileproxiesus.com/backend/api_v1/license/update-rotation-time \
  -H "x-api-key: $MPUS_API_KEY" \
  -d "uuid=$UUID" -d "minute=30"

Confirming the change

Rotation is asynchronous. On a phone line the reply comes back in about a second and the new IP lands 10 to 15 seconds later. Scripts that fire the link and immediately send the next request through the proxy will either hit a reset connection or, more confusingly, reuse the old address for one more request. Confirm first.

Three confirmation methods. On a phone line, add confirm_ip=1 to the link and the reply waits for the new IP, usually 10 to 20 seconds and at most about 90, and adds ip_changed, old_ip and new_ip. From the API: poll GET /proxy/status until ip differs. From the outside: request an IP echo service through the proxy and compare with the previous value, which is authoritative because it sees what the destination sees. Give the loop a ceiling of about 90 seconds.

def wait_new_ip(proxies, previous, timeout=45):
    import time, requests
    t0 = time.time()
    while time.time() - t0 < timeout:
        try:
            ip = requests.get("https://api.ipify.org", proxies=proxies, timeout=8).text.strip()
            if ip and ip != previous:
                return ip
        except requests.RequestException:
            pass  # connection reset mid-rotation is expected
        time.sleep(2)
    raise TimeoutError

Choosing a rotation policy

Rotate between logical units of work, not between requests. For a login session, keep the address for the whole session. For a crawl of public pages, rotate every N pages or on the first 403. For QA runs, rotate once per test case so each case starts from a fresh address and the log line for the case records which one.

Remember the pool is regional. A dozen rotations will show a dozen addresses from the carrier's pool for that metro, and over a day you will see repeats. That is normal and is what a real phone on that network looks like. GET /proxies/UUID/ip-history gives the audited record of every change if you want to look. If the job needs a different metro, move the line (free, remaining time kept) rather than rotating harder.

Frequently asked