# API de estadísticas de SMS

Cada valor del [panel Metrics](/docs/guides/sms/tracking-and-metrics) proviene de la API de estadísticas de SMS. Usa los mismos agregados en un panel, almacén de datos o comprobación de estado. Los endpoints de solo lectura, con alcance de espacio de trabajo, requieren una clave API con acceso de lectura al scope `sms`. Una respuesta coincide con el panel para el mismo rango y filtros.

Los métodos tipados se incluyen en los SDKs de [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [PHP](/docs/sdks/php) y [Go](/docs/sdks/go) bajo `sms.stats`, la [`bird` CLI](/docs/cli) los expone como `bird sms stats`, y un agente accede a ellos a través de las [herramientas MCP](/docs/ai/mcp-server) `sms_stats_*`. Los esquemas completos de solicitud y respuesta están en la [referencia de API](/docs/api/reference/get-sms-stats-summary).

## El agregado y la serie temporal

Tres endpoints cubren la parte superior del panel:

- **`GET /v1/sms/stats/summary`** devuelve una fila agregada para toda la ventana: los conteos del ciclo de vida (accepted, sent, delivered, undelivered, failed, rejected, expired), las tasas derivadas `delivery_rate` y `failure_rate`, y los percentiles de latencia de procesamiento, entrega y total (p50, p95, p99). Pasa `compare=previous_period` y la respuesta también incluye la ventana precedente de igual duración y el cambio respecto a ella.
- **`GET /v1/sms/stats/daily`** y **`GET /v1/sms/stats/hourly`** devuelven los conteos del ciclo de vida con una fila por día o por hora. Las tasas y la latencia son cifras de toda la ventana, así que léelas de `/summary` en lugar de por intervalo.

Las tasas se devuelven en **forma decimal**, así que un `delivery_rate` de `0.9739` es 97,39 %. Una tasa cuyo denominador es cero es **`null`**, que es como un período sin mensajes aceptados reporta `delivery_rate` en lugar de mostrar `0`. Las cifras usan la **hora de envío** del mensaje. Una entrega confirmada hoy para un mensaje aceptado ayer se atribuye al día de ayer. En una ventana reciente, `delivered` queda por debajo del valor final mientras siguen llegando informes de entrega. Trata las últimas horas como provisionales.

Los conteos usan agregación aproximada de mensajes distintos. Un mensaje puede contribuir a más de un estado del ciclo de vida a medida que avanza, así que los conteos por estado no son mutuamente excluyentes y no deben sumarse como total de mensajes. Usa los mensajes aceptados como denominador de la tasa de salida. Estos agregados operativos no son un registro de facturación; usa los registros de mensajes y facturación para la conciliación.

## Elegir la ventana

`from` y `to` aceptan un día calendario (`YYYY-MM-DD`) o un instante RFC 3339, y las formas que acepta cada endpoint difieren:

| Endpoint   | Límites                       | Ventana máxima                      |
| ---------- | ----------------------------- | ----------------------------------- |
| `/summary` | Ambos días, o ambos instantes | 365 días, o 720 horas con instantes |
| `/daily`   | Días calendario               | 365 días                            |
| `/hourly`  | Instantes RFC 3339            | 720 horas (30 días)                 |

Los límites con instantes tienen granularidad horaria, lo que permite hacer una ventana móvil de 24 horas en una sola solicitud. En `/summary`, mezclar un día con un instante devuelve un `422`.

Establece `timezone` con un identificador IANA como `America/New_York` para calcular los límites y los valores predeterminados omitidos en esa zona en lugar de UTC. Cuando `timezone` está definido, Bird rechaza offsets numéricos UTC como `+05:45` en los límites de instante. Usa instantes `Z` o días calendario en su lugar.

## Desgloses

Siete endpoints dividen las mismas cifras de entrega por una dimensión:

- **Adónde fue**: `/countries` (el país de destino) y `/carriers` (el operador que lo gestionó).
- **Qué enviaste**: `/originators` (la dirección de remitente con la que salió), `/categories` y `/tags`.
- **Cómo terminó**: `/statuses` (una fila por estado del ciclo de vida con actividad) y `/error-codes`.

Todos residen bajo `/v1/sms/stats/`. Las filas de país, operador, originador, categoría, etiqueta y código de error se ordenan por `sort` y se limitan con `limit` (predeterminado 50, máximo 200). Sus respuestas incluyen `total`, el número de valores distintos en la ventana, para que puedas detectar un resultado recortado. Las filas cuya métrica de ordenación es una tasa con denominador cero aparecen al final. El desglose por estado tiene como máximo siete filas y no tiene parámetros `sort` ni `limit`.

Los seis desgloses ordenados también pueden devolver una serie corta por fila. Establece `include_trend=true` y elige `trend_grain=daily` o `hourly`. Las tendencias requieren un `limit` de 50 o menos y una ventana de como máximo 90 días para intervalos diarios o 720 horas para intervalos horarios.

`sort` toma por defecto `accepted` en desgloses de volumen y `failed` en `/error-codes`. El endpoint `/error-codes` agrupa por la razón de fallo normalizada de Bird en lugar de un código de operador sin procesar. Su valor también funciona con el filtro `error_code` en [`GET /v1/sms/messages`](/docs/api/reference/list-sms-messages), vinculando una fila con sus mensajes.

`/tags` cuenta solo mensajes etiquetados, y un mensaje con varias etiquetas se cuenta una vez bajo cada una. Sus filas por tanto no suman el total del período. Concilia un resultado de `/tags` con otro en lugar de usar `/summary`.

`/statuses` devuelve un estado y un conteo en lugar del bloque de entrega completo. Cada fila cuenta los mensajes observados en ese estado del ciclo de vida; un mensaje puede aparecer en varias filas.

## Mensajes recibidos

Seis endpoints más bajo `/v1/sms/stats/inbound/` cuentan lo que tus números recibieron en lugar de lo que enviaste: `/summary`, `/daily` y `/hourly` para los totales y la serie, y `/countries`, `/operators` y `/numbers` para los desgloses. Aceptan los mismos parámetros de ventana y zona horaria que sus equivalentes de salida.

Dos cosas difieren de la familia de salida. Cada fila lleva un conteo simple `received`, sin bloque de entrega ni tasas, porque un mensaje entrante no tiene ciclo de vida de entrega que agregar. El endpoint `/operators` **excluye los mensajes cuyo operador de envío el carrier no reportó**, así que sus filas pueden sumar menos que `/inbound/summary` para el mismo período. Usa el resumen como total del espacio de trabajo; las filas de operador cubren solo mensajes con un operador reportado.

## Próximos pasos

[Analíticas de SMS](/products/sms/analytics) conectan estos informes con la revisión de campañas y la investigación de entregas.

- [Metrics](/docs/guides/sms/tracking-and-metrics): consulta el panel que muestra estos valores.
- [Log de SMS](/docs/guides/sms/sms-log): inspecciona los mensajes detrás de los agregados.
- [Events](/docs/guides/sms/events): consume el flujo de eventos detrás de los agregados.

## Related resources

- [What does a delivery receipt tell you?](/explained/sms/what-is-a-delivery-receipt) (answer)
- [Operate messaging reliably](/learn/paths/reliability) (course)

[Get an implementation brief](/learn/workspace?topic=sms-reporting)