# SMS stats API

[Metrics डैशबोर्ड](/docs/guides/sms/tracking-and-metrics) पर हर मान SMS stats API से आता है। इन्हीं एग्रीगेट का उपयोग किसी डैशबोर्ड, डेटा वेयरहाउस या हेल्थ चेक में करें। ये read-only, वर्कस्पेस-स्कोप्ड endpoints एक API key चाहते हैं जिसके पास `sms` scope का read access हो। समान रेंज और फ़िल्टर के लिए रिस्पॉन्स डैशबोर्ड से मेल खाता है।

टाइप्ड मेथड [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [PHP](/docs/sdks/php) और [Go](/docs/sdks/go) SDK में `sms.stats` के अंतर्गत उपलब्ध हैं, [`bird` CLI](/docs/cli) इन्हें `bird sms stats` के रूप में एक्सपोज़ करता है, और एक एजेंट इन तक `sms_stats_*` [MCP tools](/docs/ai/mcp-server) के ज़रिए पहुँचता है। पूर्ण request और response स्कीमा [API reference](/docs/api/reference/get-sms-stats-summary) में हैं।

## एग्रीगेट और टाइम सीरीज़

तीन endpoints डैशबोर्ड के शीर्ष भाग को कवर करते हैं:

- **`GET /v1/sms/stats/summary`** पूरी विंडो के लिए एक एग्रीगेट पंक्ति लौटाता है: लाइफसाइकल काउंट (accepted, sent, delivered, undelivered, failed, rejected, expired), व्युत्पन्न `delivery_rate` और `failure_rate`, और processing, delivery तथा total विलंब पर्सेंटाइल (p50, p95, p99)। `compare=previous_period` पास करें और रिस्पॉन्स में पूर्ववर्ती समान-लंबाई वाली विंडो और उससे हुआ परिवर्तन भी शामिल होगा।
- **`GET /v1/sms/stats/daily`** और **`GET /v1/sms/stats/hourly`** लाइफसाइकल काउंट प्रति दिन या प्रति घंटे एक पंक्ति के रूप में लौटाते हैं। दरें और विलंब पूरी-विंडो के आँकड़े हैं, इसलिए इन्हें प्रति बकेट के बजाय `/summary` से पढ़ें।

दरें **दशमलव अनुपात** के रूप में लौटती हैं, इसलिए `delivery_rate` का `0.9739` मतलब 97.39% है। जिस दर का हर शून्य हो वह **`null`** होती है, इसी तरह कोई अवधि जिसने कुछ accept नहीं किया वह `0` पढ़ने के बजाय `delivery_rate` रिपोर्ट करती है। आँकड़े संदेश के **send time** का उपयोग करते हैं। आज पुष्टि हुई कल accept किए गए संदेश की डिलीवरी कल के खाते में जाती है। इसलिए हाल की विंडो `delivered` को कम दिखाती है जब तक उसकी डिलीवरी रिपोर्ट आ रही होती हैं, अतः अंतिम कुछ घंटों को अंतिम के बजाय अस्थायी मानें।

काउंट अनुमानित distinct-message एग्रीगेशन का उपयोग करते हैं। एक संदेश आगे बढ़ते हुए एक से अधिक लाइफसाइकल स्टेटस में योगदान कर सकता है, इसलिए स्टेटस काउंट परस्पर अनन्य नहीं हैं और उन्हें संदेश कुल के रूप में जोड़ा नहीं जाना चाहिए। आउटबाउंड दर के हर के रूप में accepted संदेशों का उपयोग करें। ये ऑपरेशनल एग्रीगेट बिलिंग लेजर नहीं हैं; मिलान के लिए मैसेज और बिलिंग रिकॉर्ड का उपयोग करें।

## विंडो चुनना

`from` और `to` या तो कैलेंडर दिन (`YYYY-MM-DD`) या RFC 3339 instant लेते हैं, और कौन-सा endpoint कौन-सा फ़ॉर्म स्वीकार करता है यह भिन्न है:

| Endpoint   | सीमाएँ                      | अधिकतम विंडो                    |
| ---------- | --------------------------- | ------------------------------- |
| `/summary` | दोनों दिन, या दोनों instant | 365 दिन, या instant पर 720 घंटे |
| `/daily`   | कैलेंडर दिन                 | 365 दिन                         |
| `/hourly`  | RFC 3339 instant            | 720 घंटे (30 दिन)               |

Instant सीमाएँ hour-grain हैं, यही कारण है कि रोलिंग 24-घंटे की विंडो एक ही request में आ जाती है। `/summary` पर, किसी दिन को instant के साथ मिलाने पर `422` लौटता है।

`timezone` को कोई IANA identifier जैसे `America/New_York` सेट करें ताकि सीमाएँ और छोड़े गए डिफ़ॉल्ट UTC के बजाय उस ज़ोन में गणना हों। जब `timezone` सेट हो, तो Bird instant सीमाओं में `+05:45` जैसे न्यूमेरिक UTC ऑफ़सेट अस्वीकार कर देता है। इसके बजाय `Z` instant या कैलेंडर दिनों का उपयोग करें।

## ब्रेकडाउन

सात endpoints उन्हीं डिलीवरी संख्याओं को एक आयाम से विभाजित करते हैं:

- **कहाँ गया**: `/countries` (गंतव्य देश) और `/carriers` (जिस कैरियर ने इसे हैंडल किया)।
- **आपने क्या भेजा**: `/originators` (जिस सेंडर पते से भेजा गया), `/categories` और `/tags`।
- **कैसे समाप्त हुआ**: `/statuses` (गतिविधि वाले प्रत्येक लाइफसाइकल स्टेटस के लिए एक पंक्ति) और `/error-codes`।

ये सभी `/v1/sms/stats/` के अंतर्गत हैं। Country, carrier, originator, category, tag और error-code पंक्तियाँ `sort` के अनुसार रैंक की जाती हैं और `limit` द्वारा सीमित होती हैं (डिफ़ॉल्ट 50, अधिकतम 200)। उनके रिस्पॉन्स में `total` शामिल होता है, जो विंडो में distinct मानों की संख्या है, ताकि आप सीमित परिणाम पहचान सकें। जिन पंक्तियों का सॉर्ट मेट्रिक शून्य हर वाली दर है, वे अंत में आती हैं। स्टेटस ब्रेकडाउन में अधिकतम सात पंक्तियाँ होती हैं और इसमें `sort` या `limit` पैरामीटर नहीं होते।

छह रैंक किए गए ब्रेकडाउन प्रति पंक्ति एक छोटी सीरीज़ भी लौटा सकते हैं। `include_trend=true` सेट करें और `trend_grain=daily` या `hourly` चुनें। ट्रेंड के लिए `limit` 50 या उससे कम होना चाहिए और विंडो दैनिक बकेट के लिए अधिकतम 90 दिन या प्रति-घंटा बकेट के लिए 720 घंटे होनी चाहिए।

`sort` वॉल्यूम ब्रेकडाउन पर डिफ़ॉल्ट रूप से `accepted` और `/error-codes` पर `failed` होता है। `/error-codes` endpoint रॉ कैरियर कोड के बजाय Bird के normalized failure reason से ग्रुप करता है। इसका मान [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages) पर `error_code` फ़िल्टर के साथ भी काम करता है, जिससे एक पंक्ति उसके संदेशों से जुड़ती है।

`/tags` केवल टैग किए गए संदेशों की गणना करता है, और कई टैग वाला संदेश प्रत्येक टैग के अंतर्गत एक बार गिना जाता है। इसलिए इसकी पंक्तियाँ अवधि के कुल योग के बराबर नहीं होतीं। `/summary` के बजाय एक `/tags` परिणाम को दूसरे से मिलान करें।

`/statuses` पूर्ण डिलीवरी ब्लॉक के बजाय एक स्टेटस और काउंट लौटाता है। प्रत्येक पंक्ति उस लाइफसाइकल स्टेटस में देखे गए संदेशों की गणना करती है; एक संदेश कई पंक्तियों में दिखाई दे सकता है।

## प्राप्त संदेश

`/v1/sms/stats/inbound/` के अंतर्गत छह और endpoints यह गिनते हैं कि आपके नंबरों ने क्या प्राप्त किया, न कि आपने क्या भेजा: कुल और सीरीज़ के लिए `/summary`, `/daily` और `/hourly`, और ब्रेकडाउन के लिए `/countries`, `/operators` और `/numbers`। ये अपने आउटबाउंड समकक्षों के समान विंडो और timezone पैरामीटर लेते हैं।

आउटबाउंड फ़ैमिली से दो बातें भिन्न हैं। प्रत्येक पंक्ति में बिना डिलीवरी ब्लॉक या दरों के एक सादा `received` काउंट होता है, क्योंकि इनबाउंड संदेश का कोई डिलीवरी लाइफसाइकल एग्रीगेट करने के लिए नहीं होता। `/operators` endpoint **उन संदेशों को बाहर करता है जिनके भेजने वाले ऑपरेटर की रिपोर्ट कैरियर ने नहीं दी**, इसलिए इसकी पंक्तियों का योग उसी अवधि के `/inbound/summary` से कम हो सकता है। वर्कस्पेस कुल के रूप में summary का उपयोग करें; ऑपरेटर पंक्तियाँ केवल रिपोर्ट किए गए ऑपरेटर वाले संदेशों को कवर करती हैं।

## अगले कदम

[SMS analytics](/products/sms/analytics) इस रिपोर्टिंग को अभियान समीक्षा और डिलीवरी जाँच से जोड़ता है।

- [Metrics](/docs/guides/sms/tracking-and-metrics): वह डैशबोर्ड देखें जिसे ये मान रेंडर करते हैं।
- [SMS log](/docs/guides/sms/sms-log): एग्रीगेट के पीछे के संदेश देखें।
- [Events](/docs/guides/sms/events): एग्रीगेट के पीछे की इवेंट स्ट्रीम का उपभोग करें।

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