# SMS stats API

Elke waarde op het [Metrics-dashboard](/docs/guides/sms/tracking-and-metrics) komt uit de SMS stats API. Gebruik dezelfde aggregaten in een dashboard, datawarehouse of health check. De alleen-lezen, werkruimte-gebonden endpoints vereisen een API-sleutel met leestoegang tot het `sms`-bereik. Een antwoord komt overeen met het dashboard voor hetzelfde bereik en dezelfde filters.

Getypeerde methoden zitten in de [TypeScript](/docs/sdks/typescript)-, [Python](/docs/sdks/python)-, [PHP](/docs/sdks/php)- en [Go](/docs/sdks/go)-SDK's onder `sms.stats`, de [`bird` CLI](/docs/cli) biedt ze aan als `bird sms stats`, en een agent bereikt ze via de `sms_stats_*` [MCP tools](/docs/ai/mcp-server). Volledige request- en responseschema's staan in de [API-referentie](/docs/api/reference/get-sms-stats-summary).

## Het aggregaat en de tijdreeks

Drie endpoints bestrijken de bovenkant van het dashboard:

- **`GET /v1/sms/stats/summary`** geeft één aggregaatrij terug voor het hele venster: de lifecycletellingen (accepted, sent, delivered, undelivered, failed, rejected, expired), de afgeleide `delivery_rate` en `failure_rate`, en de verwerkings-, bezorgings- en totale latentiepercentielen (p50, p95, p99). Geef `compare=previous_period` mee en het antwoord bevat ook het voorafgaande venster van gelijke lengte en de verandering ten opzichte daarvan.
- **`GET /v1/sms/stats/daily`** en **`GET /v1/sms/stats/hourly`** geven de lifecycletellingen terug met één rij per dag of per uur. Percentages en latentie zijn cijfers over het hele venster, dus lees die uit `/summary` in plaats van per bucket.

Elke ratio komt terug als een **decimaal getal**, dus een `delivery_rate` van `0.9739` is 97,39%. Een ratio waarvan de noemer nul is, is **`null`**. Zo rapporteert een periode zonder geaccepteerde berichten `delivery_rate` in plaats van `0` te tonen. Cijfers gebruiken de **verzendtijd** van het bericht. Een bezorging die vandaag bevestigd is voor een bericht dat gisteren geaccepteerd werd, telt mee bij gisteren. Een recent venster rapporteert `delivered` daarom te laag zolang de bezorgingsrapporten nog binnenkomen, dus beschouw de laatste paar uur als voorlopig in plaats van definitief.

Tellingen gebruiken benaderende unieke-berichtaggregatie. Een bericht kan bijdragen aan meer dan één lifecyclestatus naarmate het vordert, dus statustellingen sluiten elkaar niet uit en mogen niet bij elkaar opgeteld worden als berichttotaal. Gebruik geaccepteerde berichten als noemer voor de uitgaande ratio. Deze operationele aggregaten zijn geen facturatieoverzicht; gebruik de bericht- en facturatierecords voor afstemming.

## Het venster kiezen

`from` en `to` accepteren een kalenderdag (`YYYY-MM-DD`) of een RFC 3339-tijdstip, en welke vormen een endpoint accepteert verschilt:

| Endpoint   | Grenzen                           | Maximaal venster                      |
| ---------- | --------------------------------- | ------------------------------------- |
| `/summary` | Beide dagen, of beide tijdstippen | 365 dagen, of 720 uur bij tijdstippen |
| `/daily`   | Kalenderdagen                     | 365 dagen                             |
| `/hourly`  | RFC 3339-tijdstippen              | 720 uur (30 dagen)                    |

Tijdstipgrenzen hebben uurgranulariteit, waardoor een rollend 24-uursvenster één enkel request is. Bij `/summary` levert het combineren van een dag met een tijdstip een `422` op.

Stel `timezone` in op een IANA-identificatie zoals `America/New_York` om grenzen en weggelaten standaardwaarden in die tijdzone te berekenen in plaats van UTC. Wanneer `timezone` is ingesteld, weigert Bird numerieke UTC-offsets zoals `+05:45` in tijdstipgrenzen. Gebruik in plaats daarvan `Z`-tijdstippen of kalenderdagen.

## Uitsplitsingen

Zeven endpoints splitsen dezelfde bezorgingscijfers uit op één dimensie:

- **Waar het naartoe ging**: `/countries` (het bestemmingsland) en `/carriers` (de carrier die het afhandelde).
- **Wat je verstuurde**: `/originators` (het afzenderadres waarmee het werd verzonden), `/categories` en `/tags`.
- **Hoe het eindigde**: `/statuses` (één rij per lifecyclestatus met activiteit) en `/error-codes`.

Ze vallen allemaal onder `/v1/sms/stats/`. Land-, carrier-, originator-, categorie-, tag- en foutcoderijen worden gerangschikt op `sort` en begrensd door `limit` (standaard 50, maximaal 200). Hun antwoorden bevatten `total`, het aantal unieke waarden in het venster, zodat je een begrensd resultaat kunt detecteren. Rijen waarvan de sorteermetriek een percentage met noemer nul is, verschijnen als laatste. De statusuitsplitsing heeft maximaal zeven rijen en heeft geen `sort`- of `limit`-parameters.

De zes gerangschikte uitsplitsingen kunnen ook een korte reeks per rij teruggeven. Stel `include_trend=true` in en kies `trend_grain=daily` of `hourly`. Trends vereisen een `limit` van 50 of minder en een venster van maximaal 90 dagen voor dagelijkse buckets of 720 uur voor buckets per uur.

`sort` is standaard `accepted` bij volume-uitsplitsingen en `failed` bij `/error-codes`. Het `/error-codes`-endpoint groepeert op de genormaliseerde faalreden van Bird in plaats van een ruwe carriercode. De waarde werkt ook met het `error_code`-filter op [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), waarmee je een rij aan zijn berichten koppelt.

`/tags` telt alleen getagde berichten, en een bericht met meerdere tags wordt één keer per tag geteld. De rijen tellen daarom niet op tot het periodetotaal. Vergelijk het ene `/tags`-resultaat met het andere in plaats van `/summary` te gebruiken.

`/statuses` geeft een status en telling terug in plaats van het volledige bezorgingsblok. Elke rij telt berichten die in die lifecyclestatus zijn waargenomen; een bericht kan in meerdere rijen voorkomen.

## Ontvangen berichten

Zes extra endpoints onder `/v1/sms/stats/inbound/` tellen wat je nummers ontvingen in plaats van wat je verstuurde: `/summary`, `/daily` en `/hourly` voor de totalen en de reeks, en `/countries`, `/operators` en `/numbers` voor de uitsplitsingen. Ze accepteren dezelfde venster- en tijdzoneparameters als hun uitgaande tegenhangers.

Twee dingen wijken af van de uitgaande familie. Elke rij bevat een gewone `received`-telling, zonder bezorgingsblok of ratio’s, omdat een inkomend bericht geen bezorgingslevenscyclus heeft om te aggregeren. Het `/operators`-endpoint **sluit berichten uit waarvan de carrier de verzendende operator niet rapporteerde**, waardoor de rijen lager kunnen uitvallen dan `/inbound/summary` voor dezelfde periode. Gebruik de samenvatting als werkruimtetotaal; operatorrijen dekken alleen berichten met een gerapporteerde operator.

## Volgende stappen

[SMS analytics](/products/sms/analytics) verbindt deze rapportage met campagnebeoordeling en bezorgingsonderzoek.

- [Metrics](/docs/guides/sms/tracking-and-metrics): bekijk het dashboard dat deze waarden weergeeft.
- [SMS-log](/docs/guides/sms/sms-log): bekijk de berichten achter de aggregaten.
- [Events](/docs/guides/sms/events): consumeer de eventstream achter de aggregaten.

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