Aggregate SMS stats summary
GET
/v1/sms/stats/summary
const summary = await bird.sms.stats.summary({
from: "2026-05-01", // both calendar days for a day window, or
to: "2026-05-31", // both RFC 3339 instants for an hour window
});
console.log(summary.delivery, summary.latency);summary = client.sms.stats.summary(from_="2026-05-01", to="2026-05-31")
print(summary.delivery, summary.latency)summary, err := client.Sms.Stats.Summary(context.Background(), bird.SmsStatsSummaryParams{
From: "2026-05-01", // a calendar day for a day-grain window (up to 365 days), or
To: "2026-05-31", // an RFC 3339 instant (e.g. "2026-05-01T00:00:00Z") for hour-grain (up to 720 hours)
})
if err != nil {
log.Fatal(err)
}
fmt.Println(*summary.Delivery.Accepted, *summary.Delivery.DeliveryRate)$summary = $bird->sms->stats->summary(['from' => '2026-05-01', 'to' => '2026-05-31']);
echo $summary->getDelivery()?->getAccepted(), ' ', $summary->getDelivery()?->getDeliveryRate();bird sms stats summarycurl -X GET "https://us1.platform.bird.com/v1/sms/stats/summary" \
-H "Authorization: Bearer $TOKEN"Returns a single-row aggregate across the requested period covering SMS lifecycle counts (accepted, sent, delivered, undelivered, failed, rejected, expired) plus the derived delivery and failure rates, and processing/delivery/total latency percentiles (p50/p95/p99). Suitable for KPI tiles and dashboard headers.
Rows are attributed to send time, not event time: a delivery confirmed during the period for a message accepted earlier counts against the earlier period, not this one. A recent period therefore under-reports delivered while its delivery reports are still arriving, and its counts only ever grow toward the truth.
Rate fields are null when their denominator is zero -- for example, delivery_rate is null in a period where nothing was accepted.
from and to accept either calendar days (YYYY-MM-DD) or RFC 3339 instants. With days the window covers whole calendar days, up to 365 days. With instants the window is hour-grain -- bounds round down to the hour, both inclusive -- so a rolling window such as the last 24 hours is a single request; hour windows may span up to 720 hours (30 days), and compare=previous_period compares against the preceding equal-length hour window. Both bounds must use the same form; mixing a day and an instant returns 422. Set timezone to report in a local zone instead of UTC (it then governs the day and hour boundaries; see timezone).
Parámetros de consulta
from
string
Inclusive start of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant (rounded down to the hour). Interpreted in timezone -- a calendar day names a local day and an instant is rounded down to the local hour -- or in UTC when timezone is omitted. A numeric UTC offset (for example +05:45) is rejected when timezone is set; use a calendar day or a Z (UTC) instant. Must use the same form as to. Defaults to 30 days before to for day windows, or 168 hours (7 days) before to for hour windows, when omitted.
to
string
Inclusive end of the window: a calendar day (YYYY-MM-DD) or an RFC 3339 instant (rounded down to the hour). Interpreted in timezone -- a calendar day names a local day and an instant is rounded down to the local hour -- or in UTC when timezone is omitted. A numeric UTC offset is rejected when timezone is set; use a calendar day or a Z (UTC) instant. Must use the same form as from. Defaults to today for day windows, or the current hour for hour windows, in that timezone, when omitted. Day windows may not exceed 365 days; hour windows may not exceed 720 hours (30 days).
timezone
string
IANA timezone identifier (for example Asia/Kathmandu) to report in; defaults to UTC. Day and hour boundaries and the default window when from and to are omitted both follow it, so a calendar-day from or to names a local day. A from or to carrying its own UTC offset is rejected while this is set: pass a calendar day or a Z instant.
originator
string
Restrict the statistics to a single originator (the sender address messages were sent from). Mutually exclusive with the other dimension filters (country, category, carrier); only one may be set per request. Matches the message from.
country
string
Restrict the statistics to a single destination country, as an ISO 3166-1 alpha-2 code. Mutually exclusive with the other dimension filters (originator, category, carrier); only one may be set per request.
category
string
Restrict the statistics to a single category. Mutually exclusive with the other dimension filters (originator, country, carrier); only one may be set per request.
carrier
string
Restrict the statistics to a single delivery carrier. Mutually exclusive with the other dimension filters (originator, country, category); only one may be set per request.
compare
string
Set to previous_period to also include the same statistics for the immediately preceding window of equal length, plus the change between the two, so you can show "+X% vs last period" without a second request.
Possible values: previous_period
Carga de respuesta
period
object
obligatorio
The window the response covers (echoed back from the request, day or hour grain), plus data_as_of, the freshness boundary the data is current to.
Mostrar atributos secundarios
period.from
string
obligatorio
Inclusive start of the window the response covers -- a calendar day (YYYY-MM-DD) for day windows, or an hour boundary (RFC 3339) for hour windows.
period.to
string
obligatorio
Inclusive end of the window the response covers -- a calendar day (YYYY-MM-DD) for day windows, or an hour boundary (RFC 3339) for hour windows.
period.data_as_of
nullable string
The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response is near-real-time but not live; use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
delivery
object
obligatorio
Mostrar atributos secundarios
delivery.accepted
integer
obligatorio
Distinct messages accepted for sending after admission checks. This is the denominator for delivery_rate and failure_rate.
delivery.sent
integer
obligatorio
Distinct messages handed off to the carrier for delivery.
delivery.delivered
integer
obligatorio
Distinct messages the carrier confirmed as delivered to the handset.
delivery.undelivered
integer
obligatorio
Distinct messages the carrier reported as not delivered.
delivery.failed
integer
obligatorio
Distinct messages that failed during sending.
delivery.rejected
integer
obligatorio
Distinct messages rejected before any send attempt, for example by sending policy or a message-generation failure.
delivery.expired
integer
obligatorio
Distinct messages that could not be delivered within their validity window and expired.
delivery.delivery_rate
nullable number
obligatorio
Share of accepted messages that were delivered, computed as delivered / accepted. Null when no messages were accepted in scope.
delivery.failure_rate
nullable number
obligatorio
Share of accepted messages that ultimately failed, computed as (undelivered + failed + expired) / accepted. Null when no messages were accepted in scope.
latency
object
obligatorio
Mostrar atributos secundarios
latency.processing
object
p50, p95, and p99 latency percentiles in milliseconds for one latency family over the scope. Percentiles are approximate (computed from a high-volume aggregation pipeline). All three are null together when no qualifying event contributed a latency measurement in scope.
Mostrar atributos secundarios
latency.processing.p50_ms
nullable integer
obligatorio
Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.processing.p95_ms
nullable integer
obligatorio
95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.processing.p99_ms
nullable integer
obligatorio
99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.delivery
object
p50, p95, and p99 latency percentiles in milliseconds for one latency family over the scope. Percentiles are approximate (computed from a high-volume aggregation pipeline). All three are null together when no qualifying event contributed a latency measurement in scope.
Mostrar atributos secundarios
latency.delivery.p50_ms
nullable integer
obligatorio
Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.delivery.p95_ms
nullable integer
obligatorio
95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.delivery.p99_ms
nullable integer
obligatorio
99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.total
object
p50, p95, and p99 latency percentiles in milliseconds for one latency family over the scope. Percentiles are approximate (computed from a high-volume aggregation pipeline). All three are null together when no qualifying event contributed a latency measurement in scope.
Mostrar atributos secundarios
latency.total.p50_ms
nullable integer
obligatorio
Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.total.p95_ms
nullable integer
obligatorio
95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
latency.total.p99_ms
nullable integer
obligatorio
99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison
object
Mostrar atributos secundarios
comparison.period
object
obligatorio
The preceding window these comparison figures cover -- the equal-length window ending immediately before the requested start (the prior day for day windows, the prior hour for hour windows).
Mostrar atributos secundarios
comparison.period.from
string
obligatorio
Inclusive start of the window the response covers -- a calendar day (YYYY-MM-DD) for day windows, or an hour boundary (RFC 3339) for hour windows.
comparison.period.to
string
obligatorio
Inclusive end of the window the response covers -- a calendar day (YYYY-MM-DD) for day windows, or an hour boundary (RFC 3339) for hour windows.
comparison.period.data_as_of
nullable string
The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response is near-real-time but not live; use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.
comparison.delivery
object
obligatorio
Mostrar atributos secundarios
comparison.delivery.accepted
integer
obligatorio
Distinct messages accepted for sending after admission checks. This is the denominator for delivery_rate and failure_rate.
comparison.delivery.sent
integer
obligatorio
Distinct messages handed off to the carrier for delivery.
comparison.delivery.delivered
integer
obligatorio
Distinct messages the carrier confirmed as delivered to the handset.
comparison.delivery.undelivered
integer
obligatorio
Distinct messages the carrier reported as not delivered.
comparison.delivery.failed
integer
obligatorio
Distinct messages that failed during sending.
comparison.delivery.rejected
integer
obligatorio
Distinct messages rejected before any send attempt, for example by sending policy or a message-generation failure.
comparison.delivery.expired
integer
obligatorio
Distinct messages that could not be delivered within their validity window and expired.
comparison.delivery.delivery_rate
nullable number
obligatorio
Share of accepted messages that were delivered, computed as delivered / accepted. Null when no messages were accepted in scope.
comparison.delivery.failure_rate
nullable number
obligatorio
Share of accepted messages that ultimately failed, computed as (undelivered + failed + expired) / accepted. Null when no messages were accepted in scope.
comparison.latency
object
obligatorio
Mostrar atributos secundarios
comparison.latency.processing
object
p50, p95, and p99 latency percentiles in milliseconds for one latency family over the scope. Percentiles are approximate (computed from a high-volume aggregation pipeline). All three are null together when no qualifying event contributed a latency measurement in scope.
Mostrar atributos secundarios
comparison.latency.processing.p50_ms
nullable integer
obligatorio
Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.processing.p95_ms
nullable integer
obligatorio
95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.processing.p99_ms
nullable integer
obligatorio
99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.delivery
object
p50, p95, and p99 latency percentiles in milliseconds for one latency family over the scope. Percentiles are approximate (computed from a high-volume aggregation pipeline). All three are null together when no qualifying event contributed a latency measurement in scope.
Mostrar atributos secundarios
comparison.latency.delivery.p50_ms
nullable integer
obligatorio
Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.delivery.p95_ms
nullable integer
obligatorio
95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.delivery.p99_ms
nullable integer
obligatorio
99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.total
object
p50, p95, and p99 latency percentiles in milliseconds for one latency family over the scope. Percentiles are approximate (computed from a high-volume aggregation pipeline). All three are null together when no qualifying event contributed a latency measurement in scope.
Mostrar atributos secundarios
comparison.latency.total.p50_ms
nullable integer
obligatorio
Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.total.p95_ms
nullable integer
obligatorio
95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.latency.total.p99_ms
nullable integer
obligatorio
99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
comparison.delta
object
obligatorio
Mostrar atributos secundarios
comparison.delta.accepted_pct_change
nullable number
obligatorio
Relative change in accepted messages (delivery.accepted) versus the previous period, as a signed fraction. Null when the previous period accepted none.
comparison.delta.sent_pct_change
nullable number
obligatorio
Relative change in sent messages (delivery.sent) versus the previous period, as a signed fraction. Null when the previous period had none.
comparison.delta.delivered_pct_change
nullable number
obligatorio
Relative change in delivered messages (delivery.delivered) versus the previous period, as a signed fraction. Null when the previous period delivered none.
comparison.delta.undelivered_pct_change
nullable number
obligatorio
Relative change in undelivered messages (delivery.undelivered) versus the previous period, as a signed fraction. Null when the previous period had none.
comparison.delta.failed_pct_change
nullable number
obligatorio
Relative change in failed messages (delivery.failed) versus the previous period, as a signed fraction. Null when the previous period had none.
comparison.delta.rejected_pct_change
nullable number
obligatorio
Relative change in rejected messages (delivery.rejected) versus the previous period, as a signed fraction. Null when the previous period had none.
comparison.delta.expired_pct_change
nullable number
obligatorio
Relative change in expired messages (delivery.expired) versus the previous period, as a signed fraction. Null when the previous period had none.
comparison.delta.delivery_rate_pp
nullable number
obligatorio
Signed difference between this period's and the previous period's delivery rate, both fractions in [0,1] (multiply by 100 for percentage points). Null when either period's delivery rate is undefined.
comparison.delta.failure_rate_pp
nullable number
obligatorio
Signed difference between this period's and the previous period's failure rate (multiply by 100 for percentage points). Unlike the delivery rate, the failure rate is not capped at 1. Its numerator sums undelivered, failed and expired, and a message that reaches more than one of those is counted in each, so the sum can exceed the messages accepted; counts are also approximate at high volume, which moves numerator and denominator independently. The difference can therefore fall outside [-1, 1]. Null when either period's failure rate is undefined.