Riferimento API

Autenticazione e base URL

Ogni endpoint si trova sotto https://mobileproxy.app/api/v1 e richiede un bearer token. Creane uno nella dashboard in Per gli sviluppatori → Token API, oppure con POST /tokens mentre sei autenticato. Il segreto viene mostrato una sola volta — conservalo. Invialo a ogni richiesta:

Authorization: Bearer mpx_live_…

I token che iniziano con mpx_live_ sono i token del tuo account. Gli endpoint /device/* sono chiamati dall'app Android stessa e si autenticano con un token dispositivo per singolo telefono (mpxdev_…) emesso al pairing — normalmente non li chiami mai.

Gli errori sono in JSON con un messaggio leggibile e un codice per le macchine:

{ "error": "No such device.", "code": "not_found" }

Account

GET /me — chi sono? Restituisce l'account più i conteggi in tempo reale di abbonamenti e token API.

curl https://mobileproxy.app/api/v1/me \
     -H "Authorization: Bearer mpx_live_…"

# → { "id": "u_8c31f0", "email": "you@example.com",
#     "created_at": "2026-06-28T14:02:11.000Z",
#     "subscriptions": 3, "api_tokens": 2,
#     "plan": "beta", "balance": "0.00" }

Abbonamenti

Un abbonamento (id sub_…) è lo slot durevole che possiedi: il suo name amichevole, le impostazioni e i proxy persistono anche quando cambia il telefono al di sotto. Il suo device è il telefono che lo alimenta al momento (o null quando non è associato), ed è sostituibile — una sostituzione mantiene ogni endpoint proxy.

Elenca gli abbonamenti — ciascuno con il proprio dispositivo associato unito allo stato del gateway in tempo reale (online = il tunnel proxy è attivo):

curl https://mobileproxy.app/api/v1/subscriptions \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscriptions": [ {
#     "id": "sub_760c1fc8ddab", "name": "Paris SFR",
#     "status": "active", "wifi_split": true, "created_at": "…",
#     "device": { "id": "phone_ac862619408e", "model": "Galaxy S8",
#                 "hardware_id": "352091081234567", "hardware_type": "imei",
#                 "status": "online", "exit_ip": "77.136.66.63",
#                 "carrier": "SFR", "last_seen": "…", "paired_at": "…" } } ] }

Crea un abbonamento (non associato), poi associa o sostituisci il telefono. POST /subscriptions/{id}/pair restituisce un PIN valido ~3 minuti; inserito nell'app Android, associa il telefono. Su uno slot che ha già un dispositivo si tratta di una sostituzione (mode: "swap") — il vecchio telefono viene dismesso e ogni proxy mantiene il proprio host:port e le credenziali:

curl -X POST https://mobileproxy.app/api/v1/subscriptions \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" -d '{ "name": "Paris SFR" }'
# → { "id": "sub_760c1fc8ddab", "status": "unpaired", "device": null, … }

# Pair (or swap) a phone into it
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/pair \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "mode": "new",
#     "pairing": { "pin": "483-119-702", "expires_at": "…" }, … }

Ottieni, aggiorna o annulla un abbonamento. POST modifica il nome, una description libera (max 200 caratteri, null la cancella), la preferenza wifi_split (messa in coda per il telefono associato, applicata al suo prossimo poll ~25 s), oppure shared_speed_kbps — come la velocità del dispositivo viene ripartita tra i suoi proxy. -1 (consigliato) la condivide automaticamente: il control plane misura la velocità reale del dispositivo dal throughput dal vivo (riequilibrio ~3 s), i proxy attivi nello stesso momento convergono verso quote uguali e un proxy che lavora da solo ottiene la velocità piena. Un valore > 0 ripartisce nello stesso modo quel totale fisso del dispositivo. I valori speed_limit_kbps per singolo proxy vengono conservati ma non applicati finché uno dei due è attivo; 0 disattiva la condivisione. DELETE smantella il suo dispositivo e i proxy, rilascia le porte del gateway ed elimina lo storico dello slot — irreversibile:

# Fetch one subscription
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID \
     -H "Authorization: Bearer mpx_live_…"

# Rename / describe / set Wi-Fi split / share the device's speed equally (auto)
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Paris SFR", "description": "Client X — farm slot 2", "wifi_split": true, "shared_speed_kbps": -1 }'

# Cancel (irreversible)
curl -X DELETE https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID \
     -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "id": "sub_760c1fc8ddab" }

Proxy

Un proxy è un singolo endpoint mono-protocollo (SOCKS5 oppure HTTP) su un dispositivo, con la propria autenticazione, whitelist di IP di origine, limite di velocità e regole di dominio. Quanti un dispositivo può servirne contemporaneamente è un diritto del piano (10 su Standard, 20 su Pro) — creane uno per cliente o strumento e revocane uno qualsiasi senza toccare gli altri. Una creazione oltre il limite del tuo piano restituisce 409 proxy_limit_reached.

Crea un proxy — genera una nuova coppia username/password; la password viene restituita in chiaro una sola volta, qui. Scegli protocol (socks5 o http) e, facoltativamente, passa traffic_limit_bytes per dargli un tetto di traffico rigido fin dall'inizio:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "protocol": "socks5", "traffic_limit_bytes": 5368709120 }'

# → { "id": "acc_5f734b9270e8", "subscription_id": "sub_760c1fc8ddab",
#     "protocol": "socks5",
#     "host": "173.249.36.102", "host_v6": "2a02:c207:2319:6018::1",
#     "port": 30000,
#     "username": "u04c770", "password": "k7Qp2mXe9wZ4",
#     "endpoint": "socks5://u04c770:k7Qp2mXe9wZ4@173.249.36.102:30000",
#     "endpoint_ipv6": "socks5://u04c770:k7Qp2mXe9wZ4@[2a02:c207:2319:6018::1]:30000",
#     "ip_whitelist": [], "speed_limit_kbps": 0,
#     "domain_mode": "none", "domain_rules": [],
#     "status": "active", "traffic_limit_bytes": 5368709120, "bytes_used": 0,
#     "over_limit": false, "created_at": "…" }

Modifica la policy di un proxy — modalità di autenticazione, whitelist IP, limite di velocità e regole di dominio, applicate dal vivo al gateway (protocol è fisso — elimina e ricrea invece):

curl -X PATCH \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "speed_limit_kbps": 2000,
        "domain_mode": "whitelist", "domain_rules": ["api.example.com"] }'

Elenca i proxy — su un dispositivo, oppure ogni proxy dell'intero account:

# One device
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies \
     -H "Authorization: Bearer mpx_live_…"

# Account-wide
curl https://mobileproxy.app/api/v1/proxies \
     -H "Authorization: Bearer mpx_live_…"
# → { "proxies": [ { …Proxy… }, … ] }

Proxy funzionanti con i loro IP di uscita — l’elenco a livello di account riporta l’exit_ip corrente di ogni proxy, lo stato in tempo reale del dispositivo e un verdetto working (dispositivo online, nessun blocco di fatturazione o manuale, non oltre il proprio limite di traffico; not_working_reason spiega il motivo). Filtra con ?working=true e aggiungi ?unique_ip=true per mantenere un solo proxy per ogni IP di uscita distinto — due SIM dietro lo stesso NAT dell’operatore vengono inoltre segnalate tramite duplicate_ip:

# Working proxies only, one per distinct exit IP — a paste-ready pool
curl "https://mobileproxy.app/api/v1/proxies?working=true&unique_ip=true" \
     -H "Authorization: Bearer mpx_live_…"
# → { "proxies": [ {
#       "endpoint": "socks5://user:pass@173.249.36.102:30012",
#       "exit_ip": "77.136.66.44", "device_status": "online",
#       "working": true, "not_working_reason": null,
#       "duplicate_ip": false, … }, … ] }

Revoca un proxy — arresta immediatamente quel singolo listener; ogni altro proxy sul dispositivo continua a funzionare:

curl -X DELETE \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID \
  -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "id": "acc_5f734b9270e8" }

Limiti di utilizzo per proxy e scadenza

Assegna a qualsiasi proxy un limite di utilizzo — ideale quando rivendi l'accesso e conteggi ogni cliente su un'allocazione di dati. Impostalo o modificalo in qualsiasi momento (0 lo cancella), alla creazione, tramite PATCH o con l'endpoint dedicato qui sotto. Quando bytes_used raggiunge il tetto, il proxy viene bloccato: mantiene la porta e le credenziali ma rifiuta ogni richiesta, e over_limit diventa true. Alza il limite oltre la quantità utilizzata — o cancellalo — e il proxy riprende immediatamente, stesso endpoint, senza riconfigurazione. L'elenco dei proxy riporta anche per ciascuno traffic_limit_bytes, bytes_used in tempo reale e over_limit.

curl -X POST \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/limit \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "traffic_limit_bytes": 10737418240 }'   # 10 GB — or 0 to remove
# → { "proxy_id": "acc_5f734b9270e8", "subscription_id": "sub_760c1fc8ddab",
#     "traffic_limit_bytes": 10737418240, "over_limit": false }

Scadenza a tempo — assegna a un proxy un istante expires_at (ISO 8601, nel futuro) alla creazione o tramite PATCH; null cancella una scadenza in sospeso. In quel momento il proxy viene dismesso — permanentemente, a differenza del blocco reversibile del limite di utilizzo. Per rinnovare un cliente, crea un nuovo proxy (nuova porta e credenziali). Perfetto per vendere pass giornalieri/settimanali:

# A proxy that stops serving in 7 days
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "protocol": "socks5", "expires_at": "2026-07-13T09:00:00Z" }'

# Extend or clear it later
curl -X PATCH \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "expires_at": "2026-07-20T09:00:00Z" }'   # or null to remove

VPN configs (WireGuard)

Turn a SOCKS5 username/password proxy into a full-device WireGuard tunnel. Each proxy can carry one WireGuard config; creation requires the VPN add-on. Legacy OpenVPN rows remain downloadable and revocable, but new OpenVPN configs cannot be provisioned.

# Create a WireGuard config on a proxy
curl -X POST \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs \
  -H "Authorization: Bearer mpx_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "wireguard", "name": "My laptop" }'
# → { "id": "vpn_9f2c1a0b7e", "kind": "wireguard", "client_ip": "10.77.0.2",
#     "config_text": "[Interface]\nPrivateKey = …\n[Peer]\n…", … }

# List a proxy's configs (metadata + usage vs the one-config cap)
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs \
     -H "Authorization: Bearer mpx_live_…"

# Re-download the file straight to disk
curl -OJ \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs/vpn_9f2c1a0b7e/file \
  -H "Authorization: Bearer mpx_live_…"

# Revoke (drops the WireGuard peer and kills any live session)
curl -X DELETE \
  https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/proxies/PROXY_ID/vpn-configs/vpn_9f2c1a0b7e \
  -H "Authorization: Bearer mpx_live_…"

Use the file with wg-quick up ./mpx-9f2c1a0b.conf or import it into a WireGuard client. Rotating the proxy also rotates the VPN exit.

Rotazione IP

La rotazione chiede all'operatore un IP nuovo. È per dispositivo — ogni proxy sul dispositivo ottiene il nuovo IP — messa in coda per il telefono e applicata entro un ciclo di poll (~25 s).

Ruota adesso — metti in coda una rotazione una tantum:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/change-ip \
     -H "Authorization: Bearer mpx_live_…"

# → { "status": "rotating", "subscription_id": "sub_760c1fc8ddab",
#     "command_id": "cmd_a41b",
#     "note": "IP rotation on mobile networks is best-effort; …" }

Rotazione a IP unico — passa unique: true per continuare a ruotare finché l'IP di uscita non è uno non visto negli ultimi window_min minuti dello storico IP di questo abbonamento (predefinito 60, max 1440), riprovando fino a max_attempts volte (predefinito 3, max 5). Ogni tentativo costa un ciclo completo di rotazione (~30–90 s); interroga la variante GET per lo stato di avanzamento. Gli operatori possono legittimamente riemettere un IP, quindi exhausted è un esito onesto possibile:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/change-ip \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "unique": true, "window_min": 60, "max_attempts": 3 }'
# → { "status": "rotating", "request_id": "rr_18d2c4", "command_id": "cmd_a41b",
#     "unique": { "window_min": 60, "max_attempts": 3 }, … }

# Poll for the outcome (active | succeeded | exhausted | superseded | expired)
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/change-ip \
     -H "Authorization: Bearer mpx_live_…"
# → { "request_id": "rr_18d2c4", "status": "succeeded",
#     "attempts_used": 2, "attempts_max": 3, "window_min": 60,
#     "started_ip": "77.136.66.63", "result_ip": "77.136.67.101", … }

Rotazione in blocco — ruota ogni dispositivo associato in una sola chiamata con all: true, oppure un insieme scelto tramite subscription_ids (uno dei due è obbligatorio, così una richiesta malformata non può mai ruotare per errore l’intera flotta). Accetta le stesse opzioni unique dell’endpoint per abbonamento, e ogni abbonamento riporta il proprio esito — uno slot sospeso o non associato non fa mai fallire l’intero batch. Richiede il ruolo operatore per ciascun abbonamento:

# Rotate every paired device at once (explicit opt-in)…
curl -X POST https://mobileproxy.app/api/v1/proxies/rotate \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "all": true }'

# …or a chosen set, with the unique-IP options
curl -X POST https://mobileproxy.app/api/v1/proxies/rotate \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "subscription_ids": ["sub_760c1fc8ddab"], "unique": true }'
# → { "results": [ { "subscription_id": "sub_760c1fc8ddab",
#       "status": "rotating", "command_id": "…", "request_id": "rr_18d2c4" } ],
#     "rotating": 1, "skipped": 0, … }

Link di rotazione — un URL tokenizzato che ruota l'IP di questo dispositivo quando viene richiamato, senza header di autenticazione (il segreto è il token). Incollalo in qualsiasi strumento che supporti un "URL di rotazione". Elencali, creali e revocali:

# List rotation links
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation-links \
     -H "Authorization: Bearer mpx_live_…"
# → { "rotation_links": [ { "token": "rk_9f2c81d4e7",
#       "url": "https://mobileproxy.app/rotate/rk_9f2c81d4e7", "created_at": "…" } ] }

# Create one
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation-links \
     -H "Authorization: Bearer mpx_live_…"
# → { "token": "rk_9f2c81d4e7", "url": "https://mobileproxy.app/rotate/rk_9f2c81d4e7" }

# Revoke one
curl -X DELETE https://mobileproxy.app/api/v1/rotation-links/ROTATION_TOKEN \
     -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "token": "rk_9f2c81d4e7" }

Rotazione programmata (a tempo) — imposta un intervallo di rotazione automatica in minuti (0 la disattiva; max 1440). Persiste come rotation_interval_min sul dispositivo e invia un comando set_rotation_interval che il telefono applica al suo prossimo poll, così si riconnette da solo con quella cadenza:

# Read the current settings
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "interval_minutes": 0,
#     "airplane_seconds": 5, "stale_ip_alert_minutes": 0 }

# Rotate automatically every 15 minutes
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "interval_minutes": 15 }'
# → { "status": "set", "subscription_id": "sub_760c1fc8ddab",
#     "interval_minutes": 15, "airplane_seconds": 5,
#     "stale_ip_alert_minutes": 0, "command_id": "cmd_a41b" }

Timeout modalità aereo — per quanto tempo il telefono tiene attiva la modalità aereo durante ogni cambio IP (airplane_seconds, 3–60, predefinito 5). Alcuni operatori rilasciano il vecchio lease solo dopo un'attesa più lunga; aumentalo se le rotazioni continuano a restituire lo stesso IP. Si applica allo stesso modo a rotazioni programmate, da dashboard e API:

curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "airplane_seconds": 20 }'
# → { "status": "set", "subscription_id": "sub_760c1fc8ddab",
#     "interval_minutes": 15, "airplane_seconds": 20,
#     "stale_ip_alert_minutes": 0, "command_id": "cmd_b52c" }

DNS personalizzato — i resolver che il telefono usa per le risoluzioni di dominio proxate (fino a 3 letterali IP; il telefono applica il primo e riconnette il suo tunnel). Un elenco vuoto ripristina il DNS predefinito dell'operatore:

# Read
curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/dns \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "dns_servers": [] }

# Set (and later send [] to go back to carrier DNS)
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/dns \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "dns_servers": ["1.1.1.1", "8.8.8.8"] }'
# → { "status": "set", "subscription_id": "sub_760c1fc8ddab",
#     "dns_servers": ["1.1.1.1", "8.8.8.8"], "command_id": "cmd_c63d" }

Monitoraggio

Storico degli IP di uscita — gli IP di uscita recenti riportati dal telefono, deduplicati (una nuova riga solo quando l'IP è effettivamente cambiato). Il modo affidabile per verificare che una rotazione sia andata a buon fine:

curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/ip-history \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "ip_history": [
#     { "ip": "77.136.66.63", "carrier": "SFR", "ts": "…" }, … ] }

Parametri di query facoltativi: from/to (ISO 8601) delimitano la finestra, limit limita le voci (predefinito 50, max 500), e group=day restituisce invece i conteggi di cambio per giorno — passa tz come tuo offset UTC in minuti così i giorni sono raggruppati nel tuo fuso orario. È ciò che alimenta il calendario dello storico IP della dashboard:

# Entries for one day
curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/ip-history?from=2026-07-04T22:00:00Z&to=2026-07-05T22:00:00Z&limit=500" \
     -H "Authorization: Bearer mpx_live_…"

# Per-day counts for a month (tz = minutes east of UTC, e.g. 120 for CEST)
curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/ip-history?group=day&tz=120&from=2026-06-30T22:00:00Z&to=2026-07-31T22:00:00Z" \
     -H "Authorization: Bearer mpx_live_…"
# → { "subscription_id": "sub_760c1fc8ddab", "days": [
#     { "day": "2026-07-03", "changes": 9 }, { "day": "2026-07-05", "changes": 2 } ] }

Avvisi IP — il server sorveglia la tua flotta (~ogni 60 s) e apre un avviso quando serve attenzione: stale_ip quando un dispositivo è online ma il suo IP di uscita non cambia da più della soglia dell'abbonamento (imposta stale_ip_alert_minutes su /rotation; 0 = disattivato, 2–10080), e duplicate_ip quando due dei tuoi dispositivi riportano lo stesso IP di uscita (il NAT dell'operatore può assegnare un unico indirizzo a due SIM — ruotane uno per separarli). Gli avvisi si risolvono automaticamente quando la condizione cessa; compaiono anche nella campanella degli avvisi della dashboard:

# Turn on stale-IP alerts: warn after 60 min without an IP change
curl -X POST https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/rotation \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "stale_ip_alert_minutes": 60 }'

# Poll open alerts (feed this to your own monitoring)
curl https://mobileproxy.app/api/v1/alerts \
     -H "Authorization: Bearer mpx_live_…"
# → { "alerts": [
#     { "id": "42", "sub_id": "sub_760c1fc8ddab", "sub_name": "Galaxy S8",
#       "kind": "stale_ip",
#       "message": "IP unchanged for 75 min (alert threshold 60 min) — still 77.136.66.44",
#       "detail": { "ip": "77.136.66.44", "age_min": 75, "threshold_min": 60 },
#       "created_at": "…", "resolved_at": null, "seen_at": null },
#     { "id": "41", "sub_id": "sub_9d8e7f6a5b4c", "sub_name": "Galaxy A32",
#       "kind": "duplicate_ip",
#       "message": "Exit IP 77.136.67.33 is also used by “Galaxy S8” — rotate one device to separate them",
#       "detail": { "ip": "77.136.67.33",
#                   "shared_with": [ { "sub_id": "sub_760c1fc8ddab", "name": "Galaxy S8" } ] },
#       "created_at": "…", "resolved_at": null, "seen_at": null } ],
#     "unseen": 2 }

# Include resolved history; filter to one subscription
curl "https://mobileproxy.app/api/v1/alerts?status=all&subscription=SUBSCRIPTION_ID" \
     -H "Authorization: Bearer mpx_live_…"

# Reset the dashboard's unseen badge (never resolves anything)
curl -X POST https://mobileproxy.app/api/v1/alerts/seen \
     -H "Authorization: Bearer mpx_live_…"
# → { "status": "ok", "marked": 2 }

Traffico per un dispositivo — byte conteggiati al gateway, suddivisi per proxy. Utile per fatturare i clienti a cui rivendi:

curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/traffic \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab",
#     "bytes_sent": 10485760, "bytes_recv": 262144000, "bytes_total": 272629760,
#     "per_proxy": [ { "proxy_id": "acc_5f734b9270e8",
#                      "bytes_sent": 10485760, "bytes_recv": 262144000 } ] }

Dettaglio del traffico giornaliero — byte inviati/ricevuti per giorno, da campioni con risoluzione al minuto conservati sul tier web, così la serie sopravvive alle sostituzioni di dispositivo e alla dismissione dei proxy. data_since segna il campione più vecchio — i giorni precedenti non hanno dati, il che non equivale a traffico zero. Passa tz (il tuo offset UTC in minuti) così i giorni sono raggruppati nel tuo fuso orario; finestre fino a 92 giorni:

curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/traffic/by-day?tz=120" \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "tz": 120, "data_since": "…",
#     "days": [ { "day": "2026-07-06", "bytes_sent": 10485760,
#                 "bytes_recv": 262144000, "bytes_total": 272629760 } ],
#     "total": { "bytes_sent": 10485760, "bytes_recv": 262144000,
#                "bytes_total": 272629760 } }

Uptime giornaliero — secondi up/down per giorno ricavati dal registro degli heartbeat del dispositivo (unificato tra le sostituzioni di dispositivo). Misura la vitalità degli heartbeat del dispositivo (cadenza ~25 s, soglia di gap ~90 s), non l'usabilità del tunnel end-to-end. current è lo stato in questo momento; uptime_pct copre la parte osservata di ogni giorno:

curl "https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/uptime?tz=120" \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "tz": 120, "current": "up",
#     "data_since": "…",
#     "days": [ { "day": "2026-07-06", "up_seconds": 31547,
#                 "down_seconds": 253, "uptime_pct": 99.2 } ] }

Utilizzo su tutto l'account — un riepilogo su ogni dispositivo:

curl https://mobileproxy.app/api/v1/usage/summary \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscriptions": 3, "proxies": 5,
#     "bytes_sent": 31457280, "bytes_recv": 786432000, "bytes_total": 817889280 }

SMS / OTP

SMS ricevuti — messaggi in arrivo sulla SIM di questo telefono, dal più recente. Utile per leggere i codici di verifica monouso (OTP) su telefoni che possiedi. Si basa sul permesso opzionale di ricezione SMS dell'app; se è stato rifiutato sul dispositivo, l'elenco resta vuoto:

curl https://mobileproxy.app/api/v1/subscriptions/SUBSCRIPTION_ID/sms \
     -H "Authorization: Bearer mpx_live_…"

# → { "subscription_id": "sub_760c1fc8ddab", "messages": [
#     { "id": "1042", "sender": "+15550101",
#       "body": "Your verification code is 314159",
#       "received_at": "2026-07-05T14:12:00.000Z" }, … ] }

Server

Località del gateway — le località da cui vengono serviti i tuoi proxy:

curl https://mobileproxy.app/api/v1/servers/locations \
     -H "Authorization: Bearer mpx_live_…"

# → { "locations": [ { "id": "eu-de-1", "host": "173.249.36.102",
#       "region": "EU · Germany (Frankfurt)", "country": "DE",
#       "protocols": ["socks5"], "pool": "mobile" } ] }

Token API

Elenca, crea e revoca i token API. Il segreto di un token appena creato viene mostrato una sola volta — conservalo subito; non è più recuperabile. La revoca ha effetto immediato:

# List (metadata only — never the secret)
curl https://mobileproxy.app/api/v1/tokens \
     -H "Authorization: Bearer mpx_live_…"
# → { "tokens": [ { "id": "tk_51ad", "name": "storefront",
#       "prefix": "mpx_live_9f2c", "created_at": "…", "last_used_at": "…" } ] }

# Create (secret shown once)
curl -X POST https://mobileproxy.app/api/v1/tokens \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "storefront" }'
# → { "id": "tk_51ad", "name": "storefront",
#     "token": "mpx_live_9f2c81d4e7…", "prefix": "mpx_live_9f2c",
#     "scope_subscription_id": null, "readonly": false,
#     "note": "Store this token now — it will not be shown again." }

# Revoke
curl -X DELETE https://mobileproxy.app/api/v1/tokens/TOKEN_ID \
     -H "Authorization: Bearer mpx_live_…"
# → { "deleted": true, "id": "tk_51ad" }

Chiavi con ambito e in sola lettura

Delega l'accesso senza condividere il tuo account. Passa subscription_id per limitare un token a un singolo abbonamento, e readonly: true per limitarlo alle richieste GET. Un token con ambito può raggiungere solo gli endpoint di quell'abbonamento (più /me); un token in sola lettura viene rifiutato su qualsiasi scrittura. Entrambe sono restrizioni sovrapposte al tuo account — una chiave con ambito non può mai raggiungere i dati di un altro account.

# A read-only key for ONE subscription — safe to hand a teammate or a monitor
curl -X POST https://mobileproxy.app/api/v1/tokens \
     -H "Authorization: Bearer mpx_live_…" \
     -H "Content-Type: application/json" \
     -d '{ "name": "customer-42",
           "subscription_id": "sub_760c1fc8ddab",
           "readonly": true }'
# → { …, "scope_subscription_id": "sub_760c1fc8ddab", "readonly": true }

# With that key: a GET on its own subscription works…
curl https://mobileproxy.app/api/v1/subscriptions/sub_760c1fc8ddab/traffic \
     -H "Authorization: Bearer mpx_live_scoped…"     # 200

# …but another subscription, the account-wide list, or any write is refused.
curl -X POST https://mobileproxy.app/api/v1/subscriptions/sub_760c1fc8ddab/change-ip \
     -H "Authorization: Bearer mpx_live_scoped…"     # 401 (read-only)