# SMS stats API

Setiap nilai di [dasbor Metrics](/docs/guides/sms/tracking-and-metrics) berasal dari SMS stats API. Gunakan agregat yang sama di dasbor, data warehouse, atau health check. Endpoint read-only yang tercakup dalam workspace memerlukan kunci API dengan akses baca ke scope `sms`. Respons cocok dengan dasbor untuk rentang dan filter yang sama.

Metode bertipe tersedia di SDK [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [PHP](/docs/sdks/php), dan [Go](/docs/sdks/go) di bawah `sms.stats`, [`bird` CLI](/docs/cli) mengeksposnya sebagai `bird sms stats`, dan agen mengaksesnya melalui `sms_stats_*` [MCP tools](/docs/ai/mcp-server). Skema request dan response lengkap ada di [referensi API](/docs/api/reference/get-sms-stats-summary).

## Agregat dan deret waktu

Tiga endpoint mencakup bagian atas dasbor:

- **`GET /v1/sms/stats/summary`** mengembalikan satu baris agregat untuk seluruh jendela waktu: jumlah lifecycle (accepted, sent, delivered, undelivered, failed, rejected, expired), `delivery_rate` dan `failure_rate` turunannya, serta persentil latensi pemrosesan, pengiriman, dan total (p50, p95, p99). Berikan `compare=previous_period` dan respons juga menyertakan jendela waktu sebelumnya dengan panjang yang sama beserta perubahannya.
- **`GET /v1/sms/stats/daily`** dan **`GET /v1/sms/stats/hourly`** mengembalikan jumlah lifecycle satu baris per hari atau per jam. Rasio dan latensi adalah angka seluruh jendela, jadi baca dari `/summary` alih-alih per bucket.

Setiap rasio dikembalikan sebagai **angka desimal**, jadi `delivery_rate` sebesar `0.9739` berarti 97,39%. Rasio yang penyebutnya nol bernilai **`null`**, sehingga periode tanpa pesan yang diterima API melaporkan `delivery_rate` alih-alih menampilkan `0`. Angka menggunakan **waktu kirim** pesan. Pesan yang dikonfirmasi sudah sampai hari ini tetapi diterima API kemarin dicatat pada hari kemarin. Jendela waktu terkini oleh karena itu melaporkan `delivered` lebih rendah selama laporan pengirimannya masih berdatangan, jadi perlakukan beberapa jam terakhir sebagai sementara, bukan final.

Jumlah menggunakan agregasi pesan unik yang bersifat perkiraan. Satu pesan dapat berkontribusi ke lebih dari satu status lifecycle seiring prosesnya berjalan, sehingga jumlah per status tidak saling eksklusif dan tidak boleh dijumlahkan sebagai total pesan. Gunakan pesan accepted sebagai penyebut rasio pengiriman keluar. Agregat operasional ini bukan buku besar tagihan; gunakan catatan pesan dan tagihan untuk rekonsiliasi.

## Memilih jendela waktu

`from` dan `to` menerima hari kalender (`YYYY-MM-DD`) atau instant RFC 3339, dan format yang diterima setiap endpoint berbeda:

| Endpoint   | Batas                                | Jendela maksimum                     |
| ---------- | ------------------------------------ | ------------------------------------ |
| `/summary` | Keduanya hari, atau keduanya instant | 365 hari, atau 720 jam untuk instant |
| `/daily`   | Hari kalender                        | 365 hari                             |
| `/hourly`  | Instant RFC 3339                     | 720 jam (30 hari)                    |

Batas instant berpresisi jam, yang membuat jendela bergulir 24 jam hanya memerlukan satu request. Di `/summary`, mencampur hari dengan instant menghasilkan `422`.

Atur `timezone` ke identifier IANA seperti `America/New_York` untuk menghitung batas dan default yang dihilangkan di zona tersebut alih-alih UTC. Ketika `timezone` diatur, Bird menolak offset UTC numerik seperti `+05:45` pada batas instant. Gunakan instant `Z` atau hari kalender sebagai gantinya.

## Breakdown

Tujuh endpoint memecah angka pengiriman yang sama berdasarkan satu dimensi:

- **Ke mana tujuannya**: `/countries` (negara tujuan) dan `/carriers` (operator yang menanganinya).
- **Apa yang Anda kirim**: `/originators` (alamat pengirim yang digunakan), `/categories`, dan `/tags`.
- **Bagaimana hasilnya**: `/statuses` (satu baris per status lifecycle yang memiliki aktivitas) dan `/error-codes`.

Semuanya berada di bawah `/v1/sms/stats/`. Baris country, carrier, originator, category, tag, dan error-code diurutkan berdasarkan `sort` dan dibatasi oleh `limit` (default 50, maksimum 200). Responsnya menyertakan `total`, jumlah nilai unik dalam jendela waktu, sehingga Anda dapat mendeteksi hasil yang terpotong. Baris yang metrik pengurutannya berupa rasio dengan penyebut nol muncul terakhir. Breakdown status memiliki paling banyak tujuh baris dan tidak memiliki parameter `sort` atau `limit`.

Enam breakdown berperingkat juga dapat mengembalikan deret pendek per baris. Atur `include_trend=true` dan pilih `trend_grain=daily` atau `hourly`. Tren memerlukan `limit` sebesar 50 atau kurang dan jendela paling lama 90 hari untuk bucket harian atau 720 jam untuk bucket per jam.

`sort` default-nya `accepted` pada breakdown volume dan `failed` pada `/error-codes`. Endpoint `/error-codes` mengelompokkan berdasarkan alasan kegagalan yang dinormalisasi dari Bird alih-alih kode operator mentah. Nilainya juga berfungsi dengan filter `error_code` di [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), menghubungkan baris ke pesannya.

`/tags` hanya menghitung pesan bertag, dan pesan dengan beberapa tag dihitung sekali di bawah masing-masing tag. Barisnya oleh karena itu tidak berjumlah sama dengan total periode. Rekonsiliasi satu hasil `/tags` dengan yang lain alih-alih menggunakan `/summary`.

`/statuses` mengembalikan status dan jumlah, bukan blok pengiriman lengkap. Setiap baris menghitung pesan yang teramati dalam status lifecycle tersebut; satu pesan dapat muncul di beberapa baris.

## Pesan masuk

Enam endpoint lagi di bawah `/v1/sms/stats/inbound/` menghitung apa yang diterima nomor Anda, bukan apa yang Anda kirim: `/summary`, `/daily` dan `/hourly` untuk total dan deret, serta `/countries`, `/operators` dan `/numbers` untuk breakdown. Endpoint ini menerima parameter jendela waktu dan zona waktu yang sama dengan padanan pengiriman keluarnya.

Dua hal berbeda dari keluarga pengiriman keluar. Setiap baris memuat jumlah `received` biasa, tanpa blok pengiriman atau rasio, karena pesan masuk tidak memiliki lifecycle pengiriman untuk diagregasi. Endpoint `/operators` **mengecualikan pesan yang operator pengirimnya tidak dilaporkan oleh carrier**, sehingga barisnya dapat berjumlah kurang dari `/inbound/summary` untuk periode yang sama. Gunakan summary sebagai total workspace; baris operator hanya mencakup pesan dengan operator yang dilaporkan.

## Langkah selanjutnya

[Analitik SMS](/products/sms/analytics) menghubungkan pelaporan ini ke tinjauan kampanye dan investigasi pengiriman.

- [Metrics](/docs/guides/sms/tracking-and-metrics): periksa dasbor tempat nilai-nilai ini dirender.
- [Log SMS](/docs/guides/sms/sms-log): periksa pesan di balik agregat.
- [Events](/docs/guides/sms/events): konsumsi event stream di balik agregat.

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