Rotate Modem IP

POST/api/v1/admin/proxy/modems/{modem_id}/rotate

note

This endpoint requires Admin API Key authentication via the X-Admin-Key header.

IP rotation disconnects and reconnects the modem to obtain a new IP address from the carrier. The command is queued and executed by the SpiderHub agent on the next heartbeat cycle (typically within 30 seconds).

Path Parameters

modem_idstringrequired

UUID of the modem to rotate

Query Parameters

methodstringdefault: reconnect

Rotation method:

• reconnect - Disconnect and reconnect the data connection (fastest, ~10s)
• airplane - Toggle airplane mode (more thorough, ~30s)
• ussd - Send USSD code to force new IP (carrier-specific)

Response

successboolean

Whether the command was queued successfully

command_idstring

UUID of the queued command for tracking

messagestring

Human-readable status message

Request Example

curl -X POST "https://spideriq.ai/api/v1/admin/proxy/modems/{modem_id}/rotate?method=reconnect" \
  -H "X-Admin-Key: your_admin_key"

import requests

modem_id = "11111111-1111-1111-1111-111111111111"
response = requests.post(
    f"https://spideriq.ai/api/v1/admin/proxy/modems/{modem_id}/rotate",
    params={"method": "reconnect"},
    headers={"X-Admin-Key": "your_admin_key"}
)
print(response.json())

Response Example

{
  "success": true,
  "command_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
  "message": "Rotation command queued"
}

Command Lifecycle

1. Queued: Command is stored in the database with pending status
2. Picked Up: SpiderHub agent receives command on next heartbeat (~30s)
3. Processing: Agent executes the rotation method
4. Completed: Agent reports success/failure back to central API

You can check command status via the modem list endpoint - last_rotation_at will be updated when complete.

Rotation Methods Compared

Method	Speed	Reliability	Notes
reconnect	~10s	High	Drops PPP connection, reconnects
airplane	~30s	Very High	Full radio reset, guaranteed new IP
ussd	Variable	Carrier-specific	Some carriers support *99# etc.

warning

IP rotation temporarily disconnects the modem. Any active connections through that proxy will be dropped.