# API per le statistiche SMS

Ogni valore nella [dashboard Metrics](/docs/guides/sms/tracking-and-metrics) proviene dall’API per le statistiche SMS. Usa gli stessi aggregati in una dashboard, un data warehouse o un health check. Gli endpoint in sola lettura, con scope sullo spazio di lavoro, richiedono una chiave API con accesso in lettura allo scope `sms`. Una risposta corrisponde alla dashboard per lo stesso intervallo e gli stessi filtri.

I metodi tipizzati sono disponibili negli SDK [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [PHP](/docs/sdks/php) e [Go](/docs/sdks/go) sotto `sms.stats`, la [`bird` CLI](/docs/cli) li espone come `bird sms stats` e un agente li raggiunge tramite gli [strumenti MCP](/docs/ai/mcp-server) `sms_stats_*`. Gli schemi completi di richiesta e risposta sono nella [documentazione di riferimento API](/docs/api/reference/get-sms-stats-summary).

## L'aggregato e la serie temporale

Tre endpoint coprono la parte superiore della dashboard:

- **`GET /v1/sms/stats/summary`** restituisce una singola riga aggregata per l'intera finestra: i conteggi del ciclo di vita (accepted, sent, delivered, undelivered, failed, rejected, expired), i valori derivati `delivery_rate` e `failure_rate`, e i percentili di latenza di elaborazione, consegna e totale (p50, p95, p99). Passa `compare=previous_period` e la risposta include anche la finestra precedente di pari durata e la variazione rispetto a essa.
- **`GET /v1/sms/stats/daily`** e **`GET /v1/sms/stats/hourly`** restituiscono i conteggi del ciclo di vita una riga per giorno o per ora. Tassi e latenza sono cifre sull'intera finestra, quindi leggili da `/summary` anziché per singolo bucket.

Ogni tasso viene restituito come **valore decimale**, quindi un `delivery_rate` di `0.9739` corrisponde al 97,39%. Un tasso il cui denominatore è zero è **`null`**, che è il modo in cui un periodo senza messaggi accettati riporta `delivery_rate` invece di leggere `0`. Le cifre usano l’**ora di invio** del messaggio. Una consegna confermata oggi per un messaggio accettato ieri viene attribuita a ieri. In una finestra recente, `delivered` resta sotto il valore finale finché arrivano nuovi report di consegna. Considera provvisorie le ultime ore.

I conteggi usano un'aggregazione approssimativa per messaggi distinti. Un messaggio può contribuire a più di uno stato del ciclo di vita man mano che avanza, quindi i conteggi per stato non si escludono a vicenda e non vanno sommati come totale dei messaggi. Usa i messaggi accettati come denominatore del tasso in uscita. Questi aggregati operativi non sono un registro di fatturazione; usa i record dei messaggi e di fatturazione per la riconciliazione.

## Scelta della finestra

`from` e `to` accettano un giorno di calendario (`YYYY-MM-DD`) o un istante RFC 3339, e i formati accettati variano a seconda dell'endpoint:

| Endpoint   | Limiti                              | Finestra massima                  |
| ---------- | ----------------------------------- | --------------------------------- |
| `/summary` | Entrambi giorni, o entrambi istanti | 365 giorni, o 720 ore con istanti |
| `/daily`   | Giorni di calendario                | 365 giorni                        |
| `/hourly`  | Istanti RFC 3339                    | 720 ore (30 giorni)               |

I limiti istantanei hanno granularità oraria, il che permette di ottenere una finestra mobile di 24 ore con una sola richiesta. Su `/summary`, mescolare un giorno con un istante restituisce un `422`.

Imposta `timezone` su un identificatore IANA come `America/New_York` per calcolare i limiti e i valori predefiniti omessi in quel fuso orario invece di UTC. Quando `timezone` è impostato, Bird rifiuta gli offset UTC numerici come `+05:45` nei limiti istantanei. Usa invece istanti `Z` o giorni di calendario.

## Breakdown

Sette endpoint suddividono gli stessi numeri di consegna per una dimensione:

- **Dove è andato**: `/countries` (il paese di destinazione) e `/carriers` (l'operatore che lo ha gestito).
- **Cosa hai inviato**: `/originators` (l'indirizzo mittente usato per l'invio), `/categories` e `/tags`.
- **Come è finito**: `/statuses` (una riga per ogni stato del ciclo di vita con attività) e `/error-codes`.

Tutti risiedono sotto `/v1/sms/stats/`. Le righe per paese, operatore, originator, categoria, tag e codice di errore sono ordinate per `sort` e limitate da `limit` (predefinito 50, massimo 200). Le risposte includono `total`, il numero di valori distinti nella finestra, per individuare un risultato troncato. Le righe la cui metrica di ordinamento è un tasso con denominatore zero appaiono per ultime. Il breakdown per stato ha al massimo sette righe e non ha i parametri `sort` o `limit`.

I sei breakdown ordinati possono anche restituire una breve serie per riga. Imposta `include_trend=true` e scegli `trend_grain=daily` o `hourly`. I trend richiedono `limit` pari a 50 o meno e una finestra di al massimo 90 giorni per bucket giornalieri o 720 ore per bucket orari.

`sort` usa come predefinito `accepted` nei breakdown per volume e `failed` su `/error-codes`. L'endpoint `/error-codes` raggruppa per il motivo di errore normalizzato di Bird anziché per un codice operatore grezzo. Il suo valore funziona anche con il filtro `error_code` su [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), collegando una riga ai relativi messaggi.

`/tags` conta solo i messaggi taggati e un messaggio con più tag viene contato una volta per ciascuno. Le sue righe quindi non sommano al totale del periodo. Riconcilia un risultato `/tags` con un altro invece di usare `/summary`.

`/statuses` restituisce uno stato e un conteggio anziché il blocco di consegna completo. Ogni riga conta i messaggi osservati in quello stato del ciclo di vita; un messaggio può apparire in più righe.

## Messaggi ricevuti

Sei ulteriori endpoint sotto `/v1/sms/stats/inbound/` contano ciò che i tuoi numeri hanno ricevuto anziché ciò che hai inviato: `/summary`, `/daily` e `/hourly` per i totali e la serie, e `/countries`, `/operators` e `/numbers` per i breakdown. Accettano gli stessi parametri di finestra e fuso orario delle controparti in uscita.

Due aspetti differiscono dalla famiglia in uscita. Ogni riga contiene un semplice conteggio `received`, senza blocco di consegna o tassi, perché un messaggio in entrata non ha un ciclo di vita di consegna da aggregare. L'endpoint `/operators` **esclude i messaggi per i quali l'operatore mittente non è stato riportato dall'operatore di rete**, quindi le sue righe possono sommare a meno di `/inbound/summary` per lo stesso periodo. Usa il riepilogo come totale dello spazio di lavoro; le righe per operatore coprono solo i messaggi con un operatore riportato.

## Passaggi successivi

Le [analisi SMS](/products/sms/analytics) collegano questi report alla revisione delle campagne e all’analisi delle consegne.

- [Metrics](/docs/guides/sms/tracking-and-metrics): esamina la dashboard che questi valori alimentano.
- [SMS log](/docs/guides/sms/sms-log): esamina i messaggi dietro gli aggregati.
- [Events](/docs/guides/sms/events): consuma il flusso di eventi dietro gli aggregati.

## Related resources

- [What does a delivery receipt tell you?](/explained/sms/what-is-a-delivery-receipt) (answer)
- [Operate messaging reliably](/learn/paths/reliability) (course)

[Get an implementation brief](/learn/workspace?topic=sms-reporting)