Mobile proxy IP rotation API: change the IP by link or API call

How does the rotation link work?

The rotation link is a plain URL with your port ID (it looks like mob_2v8k1q; the client area shows each port's ready-made link) and an API key in it. Opening it, in a browser, a bookmark or a script, asks the modem to drop its carrier connection and attach again. The carrier then assigns an IP address, usually a different one.

Add &format=text to get only the new IP as plain text, which is handy in shell scripts. Treat the link like a password: anyone who has it can rotate your port, and the same key sent in an API call can also change your ports' settings, sub-users or IP allowlist. Create a separate key only for rotation links, keep the link out of shared documents and chat previews, and revoke the key in the client area if it leaks.

# Replace {port} with your port ID (e.g. mob_2v8k1q, not 7777) and API_KEY with your key
curl "https://cellmast.com/api/v1/mobile/{port}/rotate?key=API_KEY"

# Plain-text answer: just the new IP
curl "https://cellmast.com/api/v1/mobile/{port}/rotate?key=API_KEY&format=text"

How do I rotate from a script with the REST API?

Scripts should use POST with the key in the Authorization header, so the key does not end up in server logs or browser history. The response tells you the new IP and when the next rotation is allowed.

curl -X POST "https://cellmast.com/api/v1/mobile/PORT_ID/rotate" \
  -H "Authorization: Bearer API_KEY"

{
  "ip": "203.0.113.24",
  "previousIp": "198.51.100.7",
  "rotatedAt": "2026-10-13T09:41:07Z",
  "nextRotationAvailableAt": "2026-10-13T09:41:37Z"
}

What happens if I rotate too often?

A port accepts at most one manual rotation every 30 seconds. A call before that returns HTTP 429 with the error rotation_too_soon and a Retry-After header that gives the seconds to wait. Nothing breaks: the port keeps its current IP.

Rotating as fast as possible is rarely useful. During each reconnect the port carries no traffic, and a carrier can hand back the same address. The rotation strategy guide suggests intervals per task.

HTTP/1.1 429 Too Many Requests
Retry-After: 22
Content-Type: application/json

{
  "error": {
    "code": "rotation_too_soon",
    "message": "Next rotation available in 22 seconds",
    "details": { "retryAfter": 22 },
    "requestId": "req_2b7c11"
  }
}

How do I set automatic rotation on a timer?

Set the port's rotation mode to interval and choose a number of minutes from 2 to 1,440 (every 2 minutes to every 24 hours). The timer then rotates the port without any call from you. Switch back to manual to stop it. You can also set the timer from the client area.

curl -X PATCH "https://cellmast.com/api/v1/mobile/PORT_ID" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rotation": {"mode": "interval", "intervalMinutes": 10}}'

# back to manual rotation
curl -X PATCH "https://cellmast.com/api/v1/mobile/PORT_ID" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rotation": {"mode": "manual", "intervalMinutes": null}}'

How do I rotate in Python or Node.js?

Both examples rotate the port and print the new IP; the Python example then sends a request through the port. The Python guide adds retries and a rotation helper.

import requests

API = "https://cellmast.com/api/v1"
KEY = "API_KEY"
PORT_ID = "PORT_ID"
PROXY = "http://USERNAME:[email protected]:7777"

r = requests.post(f"{API}/mobile/{PORT_ID}/rotate",
                  headers={"Authorization": f"Bearer {KEY}"}, timeout=60)
if r.status_code == 429:
    print("too soon, retry after", r.headers.get("Retry-After"), "s")
else:
    r.raise_for_status()
    print("new IP:", r.json()["ip"])

print(requests.get("https://api.ipify.org",
                   proxies={"http": PROXY, "https": PROXY}, timeout=30).text)

// save as rotate.mjs (ES module), then: node rotate.mjs
const API = "https://cellmast.com/api/v1";
const res = await fetch(`${API}/mobile/PORT_ID/rotate`, {
  method: "POST",
  headers: { Authorization: "Bearer API_KEY" },
  signal: AbortSignal.timeout(60000),
});
if (res.status === 429) {
  console.log("retry after", res.headers.get("retry-after"), "s");
} else if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
} else {
  const { ip, previousIp } = await res.json();
  console.log(previousIp, "->", ip);
}

Can I move a port to another carrier, city or country?

Ask support. Need another country? Ask support: if a port is in stock there, we move your remaining days to it and settle the price difference through your balance (one move per billing period). The same applies to another carrier or city in the same country. After a move, host, port and password can change: read them again in the client area.

Can I see which IPs my port has used?

Yes. GET /api/v1/mobile/{portId}/ip-history lists the addresses assigned to the port with their times. Use it to check that rotations produce new addresses, to match your own logs, or to confirm that every address belongs to the carrier you chose. GET /api/v1/mobile/{portId}/usage shows daily traffic for information; data on a dedicated port is unlimited.

Does the rotating per-GB pool need this API?

No. The rotating mobile pool changes IP on its own: Each new connection gets an IP from the pool, usually a different one; to get a new IP on every request, send one request per connection (turn off keep-alive). You control it with the username, for example USERNAME-country-us-session-abc123-ttl-15 for a 15-minute sticky session. The rotation API is for dedicated ports, where one modem is yours and you decide when its IP changes.