Sign inGet Started

Get outbound SMS statistics by message type

GET
/v1/sms/stats/content-types
const stats = await bird.sms.stats.byContentType({
  from: "2026-05-01",
  to: "2026-05-31",
});
for (const row of stats.data ?? []) {
  console.log(row.content_type, row.delivery);
}
Response200
{
  "period": {
    "from": "2026-05-01",
    "to": "2026-05-25",
    "data_as_of": "2026-05-25T14:03:10Z"
  },
  "data": [
    {
      "content_type": "sms",
      "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": 2
}

Returns delivery counts, rates and latency grouped by SMS or MMS over the requested period. Previously recorded statistics remain attributed to SMS. New activity uses the message type, so a late MMS delivery can appear under MMS while its earlier send remains under SMS. A type-filtered delivery rate is null when that type has no accepted messages. Delivery reports belong to the period when the message was accepted, including reports received later.

Query Parameters

content_typestring

Restrict statistics to SMS or MMS. Omit to include both. This filter can be combined with an existing dimension filter where the operation supports one. Previously recorded statistics remain attributed to SMS. New activity uses the message type, so a late MMS delivery can appear under MMS while its earlier send remains under SMS.

Possible values: sms, mms

fromstring

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.

tostring

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.

timezonestring

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.

sortstring

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.

Possible values: accepted, sent, delivered, undelivered, failed, rejected, expired, delivery_rate, failure_rate

limitinteger

Maximum number of message-type rows to return, ranked by the sort field descending.

include_trendboolean

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.

trend_grainstring

Bucket grain for the trend series. Has no effect unless include_trend=true.

Possible values: daily, hourly

Response Payload

period
object
required

The 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
data
array of object
required

Message-type breakdown rows, ranked by the sort metric (default accepted) descending. Empty when no messages were sent in the period.

Show child attributes
data.content_type
string
required

Message type used for reporting. Previously recorded statistics remain attributed to SMS. New activity uses the message type.

Possible values: sms, mms

data.delivery
object
required

SMS lifecycle counts and rates for a whole period or breakdown. Counts use the message send time, so a later delivery stays attributed to the bucket in which the message was sent. Rates are null when their denominator is zero.

Show child attributes
data.latency
object
required

Latency percentiles in milliseconds for the requested scope:

  • processing: From acceptance to carrier handoff.
  • delivery: From carrier handoff to delivery confirmation.
  • total: From acceptance to delivery confirmation.

Each family is omitted when no qualifying event contributes a measurement. Individual percentiles can also be null.

Show child attributes
data.latency.processing
object

Approximate 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
object

Approximate 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_ms
nullable integer
required

Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.

data.latency.delivery.p95_ms
nullable integer
required

95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.

data.latency.delivery.p99_ms
nullable integer
required

99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.

data.latency.total
object

Approximate 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.trend
array of object

Per-bucket lifecycle counts for this message type, using trend_grain. Includes only buckets with activity. Present when include_trend=true.

Show child attributes
total
integer
required

Total number of distinct message types 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.

Continue with the documentation, guides and examples for this topic.