Get outbound SMS statistics by tag
/v1/sms/stats/tagsconst stats = await bird.sms.stats.byTag({ from: "2026-05-01", to: "2026-05-31" });
for (const row of stats.data ?? []) {
// A message carrying several tags counts once under each, so rows do not sum
// to the period total.
console.log(row.tag, row.delivery);
}stats = client.sms.stats.by_tag(from_="2026-05-01", to="2026-05-31")
for row in stats.data or []:
# A message carrying several tags counts once under each, so rows do not
# sum to the period total.
print(row.tag, row.delivery)stats, err := client.Sms.Stats.ByTag(context.Background(), bird.SmsStatsByTagParams{
From: time.Now().AddDate(0, -1, 0),
To: time.Now(),
})
if err != nil {
log.Fatal(err)
}
for _, row := range *stats.Data {
// A message carrying several tags counts once under each, so rows do not
// sum to the period total.
fmt.Println(*row.Tag, *row.Delivery.Accepted)
}$byTag = $bird->sms->stats->byTag(['from' => '2026-05-01', 'to' => '2026-05-31']);
foreach ($byTag->getData() ?? [] as $row) {
// A message carrying several tags counts once under each, so rows do not sum
// to the period total.
echo $row->getTag(), ' ', $row->getDelivery()?->getAccepted(), PHP_EOL;
}bird sms stats by-tagcurl -X GET "https://us1.platform.bird.com/v1/sms/stats/tags" \
-H "Authorization: Bearer $TOKEN" \
--url-query "sort=accepted" \
--url-query "limit=50" \
--url-query "include_trend=false" \
--url-query "trend_grain=daily"{
"period": {
"from": "2026-05-01",
"to": "2026-05-25",
"data_as_of": "2026-05-25T14:03:10Z"
},
"data": [
{
"tag": "campaign:summer_sale",
"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": 18
}
Returns delivery and latency statistics grouped by tag (name:value). Rows sort by the selected metric in descending order and are capped by limit. The default sort is accepted; the default limit is 50 and the maximum is 200.
Only tagged messages appear. A message with several tags is counted once under each, so rows do not sum to the period total.
Rows use send-time attribution, so recent periods can under-report delivered while delivery reports arrive. A request may span up to 365 days; a longer window returns 422.
Query Parameters
fromstringStart 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.
tostringEnd 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.
timezonestringIANA 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.
sortstringMetric 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.
Possible values: accepted, sent, delivered, undelivered, failed, rejected, expired, delivery_rate, failure_rate
limitintegerMaximum number of tag rows to return, ranked by the sort field descending.
include_trendbooleanWhen 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.
trend_grainstringBucket grain for the trend series. Has no effect unless include_trend=true.
Possible values: daily, hourly
Response Payload
periodThe date range the response covers (echoed back from the request), plus data_as_of, the freshness boundary the data is current to.
Show child attributes
period.fromInclusive start of the window, as a calendar day (YYYY-MM-DD) or an RFC 3339 hour boundary.
period.toInclusive end of the window, as a calendar day (YYYY-MM-DD) or an RFC 3339 hour boundary.
period.data_as_ofLatest time reflected in the statistics. More recent events might not be included yet. Null when the freshness boundary is unavailable.
dataTag breakdown rows, ranked by the sort metric (default accepted) descending. Empty when no tagged messages were sent in the period.
Show child attributes
data.tagThe tag this row aggregates, in name:value form. Each distinct name-and-value pair is its own row, and a message carrying several tags is counted once under each of them, so rows do not sum to the period total.
data.deliveryShow child attributes
data.delivery.acceptedDistinct messages accepted for sending after admission checks. This is the denominator for delivery_rate and failure_rate.
data.delivery.sentDistinct messages handed off to the carrier for delivery.
data.delivery.deliveredDistinct messages the carrier confirmed as delivered to the handset.
data.delivery.undeliveredDistinct messages the carrier reported as not delivered.
data.delivery.failedDistinct messages that failed during sending.
data.delivery.rejectedDistinct messages rejected before any send attempt, for example by sending policy or a message-generation failure.
data.delivery.expiredDistinct messages that could not be delivered within their validity window and expired.
data.delivery.delivery_rateShare of accepted messages that were delivered, computed as delivered / accepted. Null when no messages were accepted in scope.
data.delivery.failure_rateShare of accepted messages that ultimately failed, computed as (undelivered + failed + expired) / accepted. Null when no messages were accepted in scope.
data.latencyShow child attributes
data.latency.processingApproximate p50, p95, and p99 latency percentiles in milliseconds for one latency family. All three are null when no qualifying event contributed a measurement.
Show child attributes
data.latency.processing.p50_msMedian (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.processing.p95_ms95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.processing.p99_ms99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.deliveryApproximate p50, p95, and p99 latency percentiles in milliseconds for one latency family. All three are null when no qualifying event contributed a measurement.
Show child attributes
data.latency.delivery.p50_msMedian (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.delivery.p95_ms95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.delivery.p99_ms99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.totalApproximate p50, p95, and p99 latency percentiles in milliseconds for one latency family. All three are null when no qualifying event contributed a measurement.
Show child attributes
data.latency.total.p50_msMedian (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.total.p95_ms95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
data.latency.total.p99_ms99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
data.trendPer-bucket lifecycle-count series for this tag over the window, bucketed by trend_grain. Sparse, so only buckets with activity are present rather than zero-filled, unlike the daily and hourly series. Present only when include_trend=true.
Show child attributes
data.trend.bucketThe day (YYYY-MM-DD) or hour (RFC 3339, on the hour) this point covers, matching the period's grain.
data.trend.deliveryShow child attributes
data.trend.delivery.acceptedDistinct messages accepted for sending after admission checks.
data.trend.delivery.sentDistinct messages handed off to the carrier for delivery.
data.trend.delivery.deliveredDistinct messages the carrier confirmed as delivered to the handset.
data.trend.delivery.undeliveredDistinct messages the carrier reported as not delivered.
data.trend.delivery.failedDistinct messages that failed during sending.
data.trend.delivery.rejectedDistinct messages rejected before any send attempt, for example by sending policy or a message-generation failure.
data.trend.delivery.expiredDistinct messages that could not be delivered within their validity window and expired.
totalTotal number of distinct tags with activity in the period, regardless of limit. When it exceeds the number of rows returned, the ranking was capped; raise limit (up to 200) or narrow the window to see more.
Related resources
Continue with the documentation, guides and examples for this topic.