---
title: "SMS delivery stats"
method: GET
path: "/sms/stats"
tags: ["SMS"]
---

# SMS delivery stats

`GET /sms/stats`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/sms/stats`
- Auth: HTTP bearer

Retrieve aggregate SMS delivery metrics for your workspace over a rolling window: how many texts were queued, sent, delivered, failed, suppressed (skipped on purpose: no consent, opted out, no sender that reaches the country) or canceled, how many replies came in, and how many segments were billed, with delivery, failure and suppression rates. There are no open or click numbers: carriers report sent, delivered and failed only. Control the window with `days` (1–365, default 30). For the messages behind these numbers, see [List SMS messages](#get-sms). Requires the `sms:read` capability.

## Query parameters

- `days` integer

## Response `200`

The stats for the window.

- SmsStats
  - `object` 'sms_stats', required
  - `window_days` integer, required: The rolling window, in days.
  - `clamped_to_retention_days` integer, nullable, required: Non-null when the requested window exceeded the plan's log retention and was clamped to this many days.
  - `totals` object, required
    - `queued` integer, required: Queued, scheduled, or being handed to the carrier.
    - `sent` integer, required: Accepted by the carrier, no delivery receipt yet.
    - `delivered` integer, required: The carrier confirmed delivery.
    - `failed` integer, required: Refused by the carrier or a compliance check after we tried.
    - `suppressed` integer, required: Skipped on purpose before sending (consent, opt-out, reach, quiet hours). Never billed.
    - `canceled` integer, required
    - `inbound` integer, required: Texts received from recipients, including STOP/HELP keywords.
    - `segments` integer, required: Segments billed for outbound texts that reached the carrier.
  - `rates` object, required: Percentages (one decimal). delivery and failure are vs sent + delivered + failed; suppression is vs those plus suppressed.
    - `delivery` number, required
    - `failure` number, required
    - `suppression` number, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: Insufficient scope.
- `404`: SMS is not enabled for this workspace.
- `422`: Invalid `days` parameter.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)