---
title: "SMS delivery stats"
description: "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. `GET /api/v1/sms/stats`"
url: https://www.unitpost.com/docs/sms/get-sms-stats
section: "SMS API reference"
updated: 2026-10-13
---
# SMS delivery stats

`GET /api/v1/sms/stats`

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](https://www.unitpost.com/docs/sms/get-sms). Requires the `sms:read` capability.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | Window size in days (1–365). Defaults to 30; values above 365 are rejected. |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | enum | yes | One of: `sms_stats`. |
| `window_days` | integer | yes | The rolling window, in days. |
| `clamped_to_retention_days` | integer | yes | Non-null when the requested window exceeded the plan's log retention and was clamped to this many days. |
| `totals` | object | yes | — |
| `rates` | object | yes | Percentages (one decimal). delivery and failure are vs sent + delivered + failed; suppression is vs those plus suppressed. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The stats for the window. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | SMS is not enabled for this workspace. |
| 422 | Invalid `days` parameter. |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/sms/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "sms_stats",
  "window_days": 0,
  "clamped_to_retention_days": 0,
  "totals": {
    "queued": 0,
    "sent": 0,
    "delivered": 0,
    "failed": 0,
    "suppressed": 0,
    "canceled": 0,
    "inbound": 0,
    "segments": 0
  },
  "rates": {
    "delivery": 0,
    "failure": 0,
    "suppression": 0
  }
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/sms/get-sms-stats
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json