---
title: "Get outbound SMS statistics by message type"
canonical: "https://bird.com/docs/api/reference/get-sms-stats-by-content-type"
---

# Get outbound SMS statistics by message type

`GET /v1/sms/stats/content-types`

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.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

## Code samples

**TypeScript**

```ts
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);
}
```

Examples: [TypeScript](/docs/api/reference/get-sms-stats-by-content-type.ts.md) · [Python](/docs/api/reference/get-sms-stats-by-content-type.py.md) · [Go](/docs/api/reference/get-sms-stats-by-content-type.go.md) · [PHP](/docs/api/reference/get-sms-stats-by-content-type.php.md) · [CLI](/docs/api/reference/get-sms-stats-by-content-type.cli.md) · [MCP](/docs/api/reference/get-sms-stats-by-content-type.mcp.md) · [cURL](/docs/api/reference/get-sms-stats-by-content-type.curl.md)

## Example response `200`

```json
{
  "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
}
```

## Query parameters

- `content_type` (string, optional)

  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`
- `from` (string, optional): 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.
- `to` (string, optional): 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.
- `timezone` (string, optional): 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.
- `sort` (string, optional)

  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`
- `limit` (integer, optional): Maximum number of message-type rows to return, ranked by the `sort` field descending.
- `include_trend` (boolean, optional): 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_grain` (string, optional)

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

  Possible values: `daily`, `hourly`

## Header parameters

- `X-Workspace-Id` (string, optional): 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.
- `X-Organization-Id` (string, optional): 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 body

- `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.
- `period.from` (string, required): Inclusive start of the window, as a calendar day (`YYYY-MM-DD`) or an RFC 3339 hour boundary.
- `period.to` (string, required): Inclusive end of the window, as a calendar day (`YYYY-MM-DD`) or an RFC 3339 hour boundary.
- `period.data_as_of` (nullable string): Latest time reflected in the statistics. More recent events might not be included yet. Null when the freshness boundary is unavailable.
- `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.
- `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.
- `data.delivery.accepted` (integer, required): Distinct messages accepted for sending after admission checks. This is the denominator for `delivery_rate` and `failure_rate`.
- `data.delivery.sent` (integer, required): Distinct messages handed off to the carrier for delivery.
- `data.delivery.delivered` (integer, required): Distinct messages the carrier confirmed as delivered to the handset.
- `data.delivery.undelivered` (integer, required): Distinct messages the carrier reported as not delivered.
- `data.delivery.failed` (integer, required): Distinct messages that failed during sending.
- `data.delivery.rejected` (integer, required): Distinct messages rejected before any send attempt, for example by sending policy or a message-generation failure.
- `data.delivery.expired` (integer, required): Distinct messages that could not be delivered within their validity window and expired.
- `data.delivery.delivery_rate` (nullable number, required): Share of accepted messages that were delivered, computed as `delivered / accepted`. Null when no messages were accepted in scope.
- `data.delivery.failure_rate` (nullable number, required): Share of accepted messages that ultimately failed, computed as `(undelivered + failed + expired) / accepted`. Null when no messages were accepted in scope.
- `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.
- `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.
- `data.latency.processing.p50_ms` (nullable integer, required): Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
- `data.latency.processing.p95_ms` (nullable integer, required): 95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
- `data.latency.processing.p99_ms` (nullable integer, required): 99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
- `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.
- `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.
- `data.latency.total.p50_ms` (nullable integer, required): Median (50th percentile) latency in milliseconds. Null when no qualifying event contributed a measurement.
- `data.latency.total.p95_ms` (nullable integer, required): 95th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
- `data.latency.total.p99_ms` (nullable integer, required): 99th percentile latency in milliseconds. Null when no qualifying event contributed a measurement.
- `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`.
- `data.trend.bucket` (string, required): The day (YYYY-MM-DD) or hour (RFC 3339, on the hour) this point covers, matching the period's grain.
- `data.trend.delivery` (object, required): SMS lifecycle counts for a time bucket. Counts use the message send time, so a message accepted on Monday and delivered on Tuesday counts in Monday's bucket. Rates are available only for whole periods and breakdowns.
- `data.trend.delivery.accepted` (integer, required): Distinct messages accepted for sending after admission checks.
- `data.trend.delivery.sent` (integer, required): Distinct messages handed off to the carrier for delivery.
- `data.trend.delivery.delivered` (integer, required): Distinct messages the carrier confirmed as delivered to the handset.
- `data.trend.delivery.undelivered` (integer, required): Distinct messages the carrier reported as not delivered.
- `data.trend.delivery.failed` (integer, required): Distinct messages that failed during sending.
- `data.trend.delivery.rejected` (integer, required): Distinct messages rejected before any send attempt, for example by sending policy or a message-generation failure.
- `data.trend.delivery.expired` (integer, required): Distinct messages that could not be delivered within their validity window and expired.
- `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.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)
