# SMS stats API

Chaque valeur du [tableau de bord Metrics](/docs/guides/sms/tracking-and-metrics) provient de l'API de statistiques SMS. Utilisez les mêmes agrégats dans un tableau de bord, un entrepôt de données ou un bilan de santé. Les endpoints en lecture seule, limités à l'espace de travail, nécessitent une clé API avec un accès en lecture au scope `sms`. Une réponse correspond au tableau de bord pour la même plage et les mêmes filtres.

Des méthodes typées sont disponibles dans les SDK [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [PHP](/docs/sdks/php) et [Go](/docs/sdks/go) sous `sms.stats`, le [`bird` CLI](/docs/cli) les expose en tant que `bird sms stats`, et un agent y accède via les [outils MCP](/docs/ai/mcp-server) `sms_stats_*`. Les schémas complets de requête et de réponse se trouvent dans la [référence API](/docs/api/reference/get-sms-stats-summary).

## L'agrégat et la série temporelle

Trois endpoints couvrent le haut du tableau de bord :

- **`GET /v1/sms/stats/summary`** renvoie une ligne agrégée unique pour l'ensemble de la fenêtre : les compteurs de cycle de vie (accepted, sent, delivered, undelivered, failed, rejected, expired), les `delivery_rate` et `failure_rate` dérivés, et les percentiles de latence de traitement, de livraison et totale (p50, p95, p99). Passez `compare=previous_period` et la réponse inclut également la fenêtre précédente de même durée ainsi que la variation par rapport à celle-ci.
- **`GET /v1/sms/stats/daily`** et **`GET /v1/sms/stats/hourly`** renvoient les compteurs de cycle de vie à raison d'une ligne par jour ou par heure. Les taux et la latence sont des chiffres sur l'ensemble de la fenêtre : lisez-les depuis `/summary` plutôt que par intervalle.

Les taux sont renvoyés sous **forme décimale** : un `delivery_rate` de `0.9739` correspond donc à 97,39 %. Un taux dont le dénominateur est zéro vaut **`null`**, ce qui permet à une période sans message accepté d'afficher `delivery_rate` plutôt que `0`. Les chiffres utilisent l'**heure d'envoi** du message. Une livraison confirmée aujourd'hui pour un message accepté hier est comptabilisée sur la journée d'hier. Une fenêtre récente sous-estime donc `delivered` tant que ses accusés de livraison arrivent encore : considérez les dernières heures comme provisoires et non définitives.

Les compteurs utilisent une agrégation approximative de messages distincts. Un message peut contribuer à plusieurs statuts de cycle de vie au fur et à mesure de sa progression : les compteurs par statut ne sont donc pas mutuellement exclusifs et ne doivent pas être additionnés comme un total de messages. Utilisez les messages acceptés comme dénominateur du taux sortant. Ces agrégats opérationnels ne constituent pas un relevé de facturation ; utilisez les enregistrements de messages et de facturation pour la réconciliation.

## Choisir la fenêtre

`from` et `to` acceptent soit un jour calendaire (`YYYY-MM-DD`), soit un instant RFC 3339, et les formats acceptés varient selon l'endpoint :

| Endpoint   | Bornes                       | Fenêtre maximale                     |
| ---------- | ---------------------------- | ------------------------------------ |
| `/summary` | Deux jours, ou deux instants | 365 jours, ou 720 heures en instants |
| `/daily`   | Jours calendaires            | 365 jours                            |
| `/hourly`  | Instants RFC 3339            | 720 heures (30 jours)                |

Les bornes en instants sont à la granularité horaire, ce qui permet d'obtenir une fenêtre glissante de 24 heures en une seule requête. Sur `/summary`, mélanger un jour avec un instant renvoie une `422`.

Définissez `timezone` sur un identifiant IANA tel que `America/New_York` pour calculer les bornes et les valeurs par défaut omises dans ce fuseau horaire au lieu d'UTC. Lorsque `timezone` est défini, Bird rejette les décalages UTC numériques tels que `+05:45` dans les bornes en instants. Utilisez des instants `Z` ou des jours calendaires à la place.

## Ventilations

Sept endpoints découpent les mêmes chiffres de livraison selon une dimension :

- **Où c'est allé** : `/countries` (le pays de destination) et `/carriers` (l'opérateur qui l'a acheminé).
- **Ce que vous avez envoyé** : `/originators` (l'adresse d'expéditeur utilisée), `/categories` et `/tags`.
- **Comment ça s'est terminé** : `/statuses` (une ligne par statut de cycle de vie avec activité) et `/error-codes`.

Tous se trouvent sous `/v1/sms/stats/`. Les lignes par pays, opérateur, expéditeur, catégorie, tag et code d'erreur sont classées par `sort` et limitées par `limit` (50 par défaut, 200 maximum). Leurs réponses incluent `total`, le nombre de valeurs distinctes dans la fenêtre, ce qui vous permet de détecter un résultat tronqué. Les lignes dont la métrique de tri est un taux avec un dénominateur nul apparaissent en dernier. La ventilation par statut comporte au plus sept lignes et n'a pas de paramètres `sort` ou `limit`.

Les six ventilations classées peuvent aussi renvoyer une courte série par ligne. Définissez `include_trend=true` et choisissez `trend_grain=daily` ou `hourly`. Les tendances nécessitent un `limit` de 50 ou moins et une fenêtre de 90 jours maximum pour les intervalles journaliers ou de 720 heures pour les intervalles horaires.

`sort` est par défaut `accepted` sur les ventilations par volume et `failed` sur `/error-codes`. L'endpoint `/error-codes` regroupe par raison d'échec normalisée de Bird plutôt que par code opérateur brut. Sa valeur fonctionne aussi avec le filtre `error_code` sur [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), reliant une ligne à ses messages.

`/tags` ne compte que les messages tagués, et un message portant plusieurs tags est compté une fois sous chacun. Ses lignes ne totalisent donc pas le total de la période. Réconciliez un résultat `/tags` avec un autre au lieu d'utiliser `/summary`.

`/statuses` renvoie un statut et un compteur plutôt que le bloc de livraison complet. Chaque ligne compte les messages observés dans ce statut de cycle de vie ; un message peut apparaître dans plusieurs lignes.

## Messages reçus

Six endpoints supplémentaires sous `/v1/sms/stats/inbound/` comptent ce que vos numéros ont reçu plutôt que ce que vous avez envoyé : `/summary`, `/daily` et `/hourly` pour les totaux et les séries, et `/countries`, `/operators` et `/numbers` pour les ventilations. Ils acceptent les mêmes paramètres de fenêtre et de fuseau horaire que leurs homologues sortants.

Deux points diffèrent de la famille sortante. Chaque ligne porte un simple compteur `received`, sans bloc de livraison ni taux, car un message entrant n'a pas de cycle de vie de livraison à agréger. L'endpoint `/operators` **exclut les messages dont l'opérateur d'envoi n'a pas été signalé par l'opérateur chargé de l'acheminement** : ses lignes peuvent donc totaliser moins que `/inbound/summary` pour la même période. Utilisez le résumé comme total de l'espace de travail ; les lignes par opérateur ne couvrent que les messages avec un opérateur signalé.

## Étapes suivantes

[Analytique SMS](/products/sms/analytics) relie ce reporting à l'analyse de campagne et à l'investigation de livraison.

- [Metrics](/docs/guides/sms/tracking-and-metrics) : consultez le tableau de bord que ces valeurs alimentent.
- [Journal SMS](/docs/guides/sms/sms-log) : consultez les messages derrière les agrégats.
- [Events](/docs/guides/sms/events) : consommez le flux d'événements derrière les agrégats.

## 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)