# SMS-Statistik-API

Jeder Wert im [Metrics-Dashboard](/docs/guides/sms/tracking-and-metrics) stammt aus der SMS-Statistik-API. Verwenden Sie dieselben Aggregatdaten in einem Dashboard, Data Warehouse oder Health Check. Die schreibgeschützten, Workspace-bezogenen Endpunkte erfordern einen API-Schlüssel mit Lesezugriff auf den Scope `sms`. Eine Antwort stimmt mit dem Dashboard für denselben Zeitraum und dieselben Filter überein.

Typisierte Methoden sind in den [TypeScript](/docs/sdks/typescript)-, [Python](/docs/sdks/python)-, [PHP](/docs/sdks/php)- und [Go](/docs/sdks/go)-SDKs unter `sms.stats` verfügbar, die [`bird` CLI](/docs/cli) stellt sie als `bird sms stats` bereit, und ein Agent erreicht sie über die `sms_stats_*` [MCP-Tools](/docs/ai/mcp-server). Vollständige Request- und Response-Schemas finden Sie in der [API-Referenz](/docs/api/reference/get-sms-stats-summary).

## Das Aggregat und die Zeitreihe

Drei Endpunkte decken den oberen Bereich des Dashboards ab:

- **`GET /v1/sms/stats/summary`** gibt eine einzelne Aggregatzeile für das gesamte Fenster zurück: die Lifecycle-Zähler (accepted, sent, delivered, undelivered, failed, rejected, expired), die abgeleiteten `delivery_rate` und `failure_rate` sowie die Latenz-Perzentile für Verarbeitung, Zustellung und Gesamtdauer (p50, p95, p99). Übergeben Sie `compare=previous_period`, und die Antwort enthält zusätzlich das vorangehende gleichlange Fenster und die Änderung gegenüber diesem.
- **`GET /v1/sms/stats/daily`** und **`GET /v1/sms/stats/hourly`** geben die Lifecycle-Zähler mit einer Zeile pro Tag oder pro Stunde zurück. Raten und Latenz beziehen sich auf das gesamte Fenster, lesen Sie diese daher aus `/summary` statt pro Bucket.

Raten werden als **Dezimalzahlen** zurückgegeben, eine `delivery_rate` von `0.9739` entspricht also 97,39 %. Eine Rate, deren Nenner null ist, ist **`null`**. So meldet ein Zeitraum ohne akzeptierte Nachrichten `delivery_rate`, anstatt `0` anzuzeigen. Die Zahlen verwenden die **Sendezeit** der Nachricht. Eine heute bestätigte Zustellung für eine gestern akzeptierte Nachricht wird dem gestrigen Tag zugeordnet. Ein aktuelles Fenster unterschätzt daher `delivered`, solange die Zustellberichte noch eintreffen. Behandeln Sie die letzten Stunden als vorläufig, nicht als endgültig.

Die Zähler schätzen die Anzahl unterschiedlicher Nachrichten. Eine Nachricht kann im Verlauf zu mehr als einem Lifecycle-Status beitragen. Status-Zähler schließen sich daher nicht gegenseitig aus und dürfen nicht als Gesamtzahl der Nachrichten addiert werden. Verwenden Sie akzeptierte Nachrichten als Nenner der Ausgangsrate. Diese operativen Aggregatdaten sind kein Abrechnungsjournal; verwenden Sie die Nachrichten- und Abrechnungsdatensätze für den Abgleich.

## Das Fenster wählen

`from` und `to` akzeptieren entweder einen Kalendertag (`YYYY-MM-DD`) oder einen RFC-3339-Zeitpunkt, und die akzeptierten Formate unterscheiden sich je nach Endpunkt:

| Endpunkt   | Grenzen                            | Maximales Fenster                         |
| ---------- | ---------------------------------- | ----------------------------------------- |
| `/summary` | Beides Tage oder beides Zeitpunkte | 365 Tage oder 720 Stunden bei Zeitpunkten |
| `/daily`   | Kalendertage                       | 365 Tage                                  |
| `/hourly`  | RFC-3339-Zeitpunkte                | 720 Stunden (30 Tage)                     |

Zeitpunkt-Grenzen haben Stundengranularität, weshalb ein rollendes 24-Stunden-Fenster ein einzelner Request ist. Bei `/summary` gibt die Kombination eines Tages mit einem Zeitpunkt einen `422` zurück.

Setzen Sie `timezone` auf einen IANA-Bezeichner wie `America/New_York`, um Grenzen und ausgelassene Standardwerte in dieser Zeitzone statt in UTC zu berechnen. Wenn `timezone` gesetzt ist, lehnt Bird numerische UTC-Offsets wie `+05:45` in Zeitpunkt-Grenzen ab. Verwenden Sie stattdessen `Z`-Zeitpunkte oder Kalendertage.

## Aufschlüsselungen

Sieben Endpunkte gliedern dieselben Zustellzahlen nach jeweils einer Dimension:

- **Wohin es ging**: `/countries` (das Zielland) und `/carriers` (der Carrier, der die Nachricht verarbeitet hat).
- **Was Sie gesendet haben**: `/originators` (die Absenderadresse, über die es versendet wurde), `/categories` und `/tags`.
- **Wie es endete**: `/statuses` (eine Zeile pro Lifecycle-Status mit Aktivität) und `/error-codes`.

Alle befinden sich unter `/v1/sms/stats/`. Zeilen für Land, Carrier, Absender, Kategorie, Tag und Fehlercode werden nach `sort` sortiert und durch `limit` begrenzt (Standard 50, Maximum 200). Die Antworten enthalten `total`, die Anzahl der unterschiedlichen Werte im Fenster, sodass Sie ein begrenztes Ergebnis erkennen können. Zeilen, deren Sortiermetrik eine Rate mit einem Nenner von null ist, erscheinen zuletzt. Die Status-Aufschlüsselung hat maximal sieben Zeilen und besitzt keine Parameter `sort` oder `limit`.

Die sechs sortierten Aufschlüsselungen können auch eine kurze Zeitreihe pro Zeile zurückgeben. Setzen Sie `include_trend=true` und wählen Sie `trend_grain=daily` oder `hourly`. Trends erfordern einen `limit` von 50 oder weniger und ein Fenster von maximal 90 Tagen für tägliche Buckets oder 720 Stunden für stündliche Buckets.

`sort` ist bei Volumen-Aufschlüsselungen standardmäßig `accepted` und bei `/error-codes` standardmäßig `failed`. Der Endpunkt `/error-codes` gruppiert nach dem normalisierten Fehlergrund von Bird anstelle eines rohen Carrier-Codes. Sein Wert funktioniert auch mit dem Filter `error_code` auf [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), um eine Zeile mit ihren Nachrichten zu verknüpfen.

`/tags` zählt nur getaggte Nachrichten, und eine Nachricht mit mehreren Tags wird unter jedem einmal gezählt. Die Zeilen ergeben daher nicht die Gesamtzahl des Zeitraums. Gleichen Sie ein `/tags`-Ergebnis mit einem anderen ab, anstatt `/summary` zu verwenden.

`/statuses` gibt einen Status und einen Zähler zurück, nicht den vollständigen Zustellblock. Jede Zeile zählt Nachrichten, die in diesem Lifecycle-Status beobachtet wurden; eine Nachricht kann in mehreren Zeilen erscheinen.

## Empfangene Nachrichten

Sechs weitere Endpunkte unter `/v1/sms/stats/inbound/` zählen, was Ihre Nummern empfangen haben, statt was Sie gesendet haben: `/summary`, `/daily` und `/hourly` für die Gesamtwerte und die Zeitreihe, sowie `/countries`, `/operators` und `/numbers` für die Aufschlüsselungen. Sie akzeptieren dieselben Fenster- und Zeitzonenparameter wie ihre ausgehenden Gegenstücke.

Zwei Dinge unterscheiden sich von der ausgehenden Familie. Jede Zeile enthält einen einfachen `received`-Zähler ohne Zustellblock oder Raten, da eine eingehende Nachricht keinen Zustelllebenszyklus zur Aggregation hat. Der Endpunkt `/operators` **schließt Nachrichten aus, deren sendenden Betreiber der Carrier nicht gemeldet hat**, sodass seine Zeilen für denselben Zeitraum weniger als `/inbound/summary` ergeben können. Verwenden Sie die Zusammenfassung als Workspace-Gesamtwert; Betreiberzeilen decken nur Nachrichten mit einem gemeldeten Betreiber ab.

## Nächste Schritte

Die [SMS-Analysen](/products/sms/analytics) verbinden diese Berichte mit der Kampagnenauswertung und der Untersuchung von Zustellungen.

- [Metrics](/docs/guides/sms/tracking-and-metrics): Sehen Sie sich das Dashboard an, das diese Werte darstellt.
- [SMS-Log](/docs/guides/sms/sms-log): Sehen Sie sich die Nachrichten hinter den Aggregatdaten an.
- [Events](/docs/guides/sms/events): Konsumieren Sie den Event-Stream hinter den Aggregatdaten.

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