Get outbound SMS statistics by carrier
Returns aggregate delivery and latency stats grouped by delivery carrier for the requested period. Rows are ranked by the sort metric (default accepted) descending and capped at the requested limit (default 50, hard maximum 200). Use this to compare delivery performance across the carriers that handled your messages.
Rows use send-time attribution. A delivery confirmed during the period for a message accepted earlier counts against the earlier period. A recent period therefore under-reports delivered while delivery reports are still arriving, and its counts grow as reports arrive.
The maximum window is 365 days; requesting a longer range returns 422.
Request
- Base URL: https://us1.platform.bird.com
- URL: https://us1.platform.bird.com/v1/sms/stats/carriers
- Auth: one of:
- HTTP bearer
- API key in cookie bird_session
Query parameters
Start date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in timezone (a UTC day when timezone is omitted). Defaults to 30 days before to when omitted; with include_trend=true and trend_grain=hourly the default tightens to keep the window within the 720-hour trend cap.
End date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in timezone (a UTC day when timezone is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days.
IANA timezone identifier used to group statistics, for example Asia/Kathmandu. The default is UTC. Day and hour boundaries, including the default window when from and to are omitted, follow this timezone. When this parameter is set, pass from and to as calendar days or Z instants instead of timestamps with explicit UTC offsets.
Metric to rank breakdown rows by, applied descending. Shared by the volume breakdowns whose rows carry the full delivery and latency block (originators, countries, categories, carriers). Any lifecycle count or derived rate may be used; rows whose rate is undefined (zero denominator) sort last.
Metric to rank rows by, applied descending. Any lifecycle count or derived rate in the response may be used; rows whose rate is undefined (zero denominator) sort last. Defaults to accepted.
Maximum number of carrier rows to return, ranked by the sort field descending.
When true, each row also carries a trend array: a short per-bucket lifecycle-count series for that row over the window. Returned only when limit is 50 or fewer and the window is at most 90 days (trend_grain=daily) or 720 hours (trend_grain=hourly); a larger request returns 422.
Bucket grain for a stats trend series.
Bucket grain for the trend series. Has no effect unless include_trend=true.
Headers
Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.
Response
Per-carrier breakdown for the requested period.
Example response
{
"period": {
"from": "2026-05-01",
"to": "2026-05-25",
"data_as_of": "2026-05-25T14:03:10Z"
},
"data": [
{
"carrier": "Verizon",
"delivery": {
"accepted": 14820,
"sent": 14810,
"delivered": 14720,
"undelivered": 60,
"failed": 25,
"rejected": 10,
"expired": 5,
"delivery_rate": 0.9932,
"failure_rate": 0.0061
},
"latency": {
"processing": {
"p50_ms": 420,
"p95_ms": 1820,
"p99_ms": 4920
},
"delivery": {
"p50_ms": 420,
"p95_ms": 1820,
"p99_ms": 4920
},
"total": {
"p50_ms": 420,
"p95_ms": 1820,
"p99_ms": 4920
}
},
"trend": [
{
"bucket": "2026-05-25",
"delivery": {
"accepted": 14820,
"sent": 14810,
"delivered": 14720,
"undelivered": 60,
"failed": 25,
"rejected": 10,
"expired": 5
}
}
]
}
],
"total": 24
}Changes
No recorded changes to this operation across all 2 revisions of this API.