# SMS stats API

Każda wartość w [panelu Metrics](/docs/guides/sms/tracking-and-metrics) pochodzi z SMS stats API. Używaj tych samych agregatów w dashboardzie, hurtowni danych lub health checku. Endpointy tylko do odczytu, ograniczone do obszaru roboczego, wymagają klucza API z dostępem do odczytu w zakresie `sms`. Odpowiedź jest zgodna z panelem dla tego samego zakresu i filtrów.

Typowane metody są dostępne w SDK [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [PHP](/docs/sdks/php) i [Go](/docs/sdks/go) pod `sms.stats`, [`bird` CLI](/docs/cli) udostępnia je jako `bird sms stats`, a agent korzysta z nich przez `sms_stats_*` [narzędzia MCP](/docs/ai/mcp-server). Pełne schematy żądań i odpowiedzi znajdziesz w [dokumentacji API](/docs/api/reference/get-sms-stats-summary).

## Agregat i seria czasowa

Trzy endpointy obsługują górną część panelu:

- **`GET /v1/sms/stats/summary`** zwraca jeden wiersz agregatu dla całego okna: liczniki cyklu życia (accepted, sent, delivered, undelivered, failed, rejected, expired), pochodne `delivery_rate` i `failure_rate` oraz percentyle opóźnień przetwarzania, dostarczenia i całkowite (p50, p95, p99). Przekaż `compare=previous_period`, a odpowiedź uwzględni też poprzednie okno o tej samej długości i zmianę względem niego.
- **`GET /v1/sms/stats/daily`** i **`GET /v1/sms/stats/hourly`** zwracają liczniki cyklu życia, jeden wiersz na dzień lub na godzinę. Wskaźniki i opóźnienia dotyczą całego okna, więc odczytuj je z `/summary`, a nie z poszczególnych przedziałów.

Każdy wskaźnik jest zwracany jako **ułamek dziesiętny**, więc `delivery_rate` równy `0.9739` oznacza 97,39%. Wskaźnik, którego mianownik wynosi zero, ma wartość **`null`**, co pozwala okresowi bez zaakceptowanych wiadomości raportować `delivery_rate` zamiast `0`. Wartości odnoszą się do **czasu wysłania** wiadomości. Potwierdzenie dostarczenia otrzymane dziś dla wiadomości zaakceptowanej wczoraj jest liczone na poczet wczoraj. Ostatnie okno zaniża więc `delivered`, dopóki raporty dostarczeń wciąż napływają, dlatego traktuj ostatnie kilka godzin jako dane tymczasowe, nie ostateczne.

Liczniki używają przybliżonej agregacji unikalnych wiadomości. Wiadomość może pojawić się w więcej niż jednym statusie cyklu życia w miarę postępu, więc liczniki statusów nie wykluczają się wzajemnie i nie wolno ich sumować jako łącznej liczby wiadomości. Jako mianownika wskaźnika wychodzącego używaj zaakceptowanych wiadomości. Te agregaty operacyjne nie są rejestrem rozliczeniowym; do uzgodnień używaj rekordów wiadomości i rozliczeń.

## Wybór okna

`from` i `to` przyjmują dzień kalendarzowy (`YYYY-MM-DD`) lub znacznik czasu RFC 3339, a akceptowane formaty różnią się w zależności od endpointu:

| Endpoint   | Granice                         | Maksymalne okno                             |
| ---------- | ------------------------------- | ------------------------------------------- |
| `/summary` | Oba dni lub oba znaczniki czasu | 365 dni lub 720 godzin dla znaczników czasu |
| `/daily`   | Dni kalendarzowe                | 365 dni                                     |
| `/hourly`  | Znaczniki czasu RFC 3339        | 720 godzin (30 dni)                         |

Granice w znacznikach czasu mają granulację godzinową, dzięki czemu ruchome okno 24-godzinne to jedno żądanie. W `/summary` mieszanie dnia ze znacznikiem czasu zwraca `422`.

Ustaw `timezone` na identyfikator IANA, np. `America/New_York`, aby obliczać granice i pomijane wartości domyślne w tej strefie zamiast UTC. Gdy `timezone` jest ustawione, Bird odrzuca numeryczne przesunięcia UTC, takie jak `+05:45`, w granicach znaczników czasu. Używaj zamiast tego znaczników czasu `Z` lub dni kalendarzowych.

## Rozbicia

Siedem endpointów dzieli te same liczby dostarczeń według jednego wymiaru:

- **Dokąd trafiła**: `/countries` (kraj docelowy) i `/carriers` (operator, który ją obsłużył).
- **Co wysłałeś**: `/originators` (adres nadawcy, z którego wyszła), `/categories` i `/tags`.
- **Jak się zakończyła**: `/statuses` (jeden wiersz na status cyklu życia z aktywnością) i `/error-codes`.

Wszystkie znajdują się pod `/v1/sms/stats/`. Wiersze krajów, operatorów, nadawców, kategorii, tagów i kodów błędów są rankingowane według `sort` i ograniczone przez `limit` (domyślnie 50, maksymalnie 200). Odpowiedzi zawierają `total`, czyli liczbę unikalnych wartości w oknie, dzięki czemu wykryjesz obcięty wynik. Wiersze, których metryka sortowania jest wskaźnikiem z mianownikiem równym zero, pojawiają się na końcu. Rozbicie statusów ma co najwyżej siedem wierszy i nie ma parametrów `sort` ani `limit`.

Sześć rankingowanych rozbić może też zwrócić krótką serię dla każdego wiersza. Ustaw `include_trend=true` i wybierz `trend_grain=daily` lub `hourly`. Trendy wymagają `limit` równego 50 lub mniej oraz okna co najwyżej 90 dni dla przedziałów dziennych lub 720 godzin dla przedziałów godzinowych.

`sort` domyślnie przyjmuje `accepted` w rozbiciach wolumenowych i `failed` w `/error-codes`. Endpoint `/error-codes` grupuje według znormalizowanej przyczyny błędu Bird, a nie surowego kodu operatora. Jego wartość współpracuje też z filtrem `error_code` w [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), wiążąc wiersz z jego wiadomościami.

`/tags` liczy tylko otagowane wiadomości, a wiadomość z kilkoma tagami jest liczona raz pod każdym z nich. Wiersze nie sumują się więc do łącznej wartości za okres. Uzgadniaj jeden wynik `/tags` z drugim zamiast używać `/summary`.

`/statuses` zwraca status i liczbę zamiast pełnego bloku dostarczenia. Każdy wiersz liczy wiadomości zaobserwowane w danym statusie cyklu życia; wiadomość może pojawić się w kilku wierszach.

## Odebrane wiadomości

Sześć kolejnych endpointów pod `/v1/sms/stats/inbound/` liczy to, co Twoje numery odebrały, a nie to, co wysłałeś: `/summary`, `/daily` i `/hourly` dla sum i serii oraz `/countries`, `/operators` i `/numbers` dla rozbić. Przyjmują te same parametry okna i strefy czasowej co ich odpowiedniki wychodzące.

Dwie rzeczy różnią się od rodziny wychodzącej. Każdy wiersz zawiera zwykły licznik `received` bez bloku dostarczenia i wskaźników, ponieważ wiadomość przychodząca nie ma cyklu życia dostarczenia do agregowania. Endpoint `/operators` **wyklucza wiadomości, których operatora nadawczego nie zgłosił operator obsługujący wiadomość**, więc jego wiersze mogą sumować się do mniej niż `/inbound/summary` za ten sam okres. Używaj podsumowania jako łącznej wartości obszaru roboczego; wiersze operatorów obejmują tylko wiadomości ze zgłoszonym operatorem.

## Następne kroki

[Analityka SMS](/products/sms/analytics) łączy te raporty z przeglądem kampanii i badaniem dostarczeń.

- [Metrics](/docs/guides/sms/tracking-and-metrics): sprawdź panel, który te wartości renderują.
- [Log SMS](/docs/guides/sms/sms-log): sprawdź wiadomości stojące za agregatami.
- [Events](/docs/guides/sms/events): konsumuj strumień zdarzeń stojący za agregatami.

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