# Uso y límites

`GET /v1/usage`

GET /v1/usage da el consumo del período: `used`, `included`, `remaining`, `policy` (block|queue) y un `breakdown` por origen (`api`, `contact`, `device`). ⚠ **Regla del tráfico del teléfono (Coexistence):** `used = api + contact`; el tráfico `device` (lo que el dueño manda desde el celular) se muestra pero **NO consume el plan**. El límite POR NÚMERO (`monthlyMessageLimit`) cuenta **solo `api`**. Por número: `/v1/connections/:id/usage` y `/v1/usage/by-connection`; sobreventa informativa: `/v1/accounts/oversubscription`.

## Ejemplos

### cURL

```bash
curl https://api.waiaconnect.com/v1/usage \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "used": 89, "included": 25000, "remaining": 24911, "policy": "block",
#     "breakdown": { "api": 0, "contact": 89, "device": 62 },
#     "breakdownNote": "used = api + contact; device does not count" }
```

### Node.js

```javascript
const res = await fetch("https://api.waiaconnect.com/v1/usage", {
  headers: { "Authorization": "Bearer wc_live_YOUR_API_KEY" }
});
const u = await res.json();
console.log(u.used, "/", u.included); // device is in u.breakdown.device but NOT billed
```

### PHP

```php
<?php
$ch = curl_init("https://api.waiaconnect.com/v1/usage");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY"],
]);
$u = json_decode(curl_exec($ch), true);
echo $u["used"] . " / " . $u["included"]; // device is shown but not billed
```

### Python

```python
import requests
res = requests.get("https://api.waiaconnect.com/v1/usage",
  headers={"Authorization": "Bearer wc_live_YOUR_API_KEY"})
u = res.json()
print(u["used"], "/", u["included"])  # u["breakdown"]["device"] is shown but not billed
```

## Notas

- ⚠ **Sin tope de mensajes (tarifa plana):** `included` y `remaining` llegan en **`null`** y `policy` queda sin nada sobre lo que disparar — lo que define tu plan es cuántos NÚMEROS conectás, no cuántos mensajes mandás. `used` sigue midiendo todo. Un plan a medida con cupo pactado devuelve enteros en los dos.
- Los buckets se agregan en UTC; el `timezone` de la cuenta se devuelve solo para que vos armes el caption.
- ⚠⚠ **LOS LÍMITES DE META SON OTRA COSA, Y SON LOS QUE TE VAN A FRENAR.** Nosotros no te ponemos tope de mensajes; Meta sí te pone dos, y no se mezclan. (1) **CONTACTOS** — a cuánta gente DISTINTA le iniciás conversación en 24 h: **250 → 2.000 → 10.000 → 100.000 → sin límite**, y se sube con verificación del negocio, volumen y calidad. ⚠ **Desde el 7 de octubre de 2025 ese límite es por PORTAFOLIO de negocio, no por número**: todos los números del mismo portafolio COMPARTEN el cupo. Si administrás números de varios clientes, dimensioná con esto. (2) **RITMO** — qué tan rápido salen: hasta **80 mensajes/segundo** por número en la Cloud API (hasta **1.000** con el ascenso automático), y **20/segundo fijo** para un número en Coexistence; pasarte devuelve el `130429` de Meta. Del lado nuestro **no perdés mensajes por ir más rápido**: la cola los absorbe y los drena, con reintentos e idempotencia. _Verificado contra la documentación de Meta el 30/08/2026._
- Los umbrales 70/90/100% llegan por webhook (`usage.threshold_reached` / `connection.usage_threshold_reached`). ⚠ El de CUENTA es relativo al cupo del plan, así que **sin tope no se dispara**; el POR NÚMERO (`connection.usage_threshold_reached`) sí, porque ese límite lo ponés vos.
- 🔴 **ACÁ HAY DOS PAGOS, Y SON SEPARADOS.** (1) **A WAIA Connect le pagás la infraestructura**: tu plan, por número conectado, sin tope de mensajes. (2) **A Meta le pagás los mensajes**, con tu propia tarjeta cargada en tu cuenta de Meta — nosotros no lo cobramos ni lo vemos. ⚠ Las tres confusiones más caras: **la prueba gratis es NUESTRA, no de Meta** (Meta cobra desde el primer mensaje del primer día); **Meta cobra por MENSAJE entregado, no por conversación** (el precio por conversación existió hasta el **1 de julio de 2025** y Meta lo dio de baja — quien estima por conversación calcula de menos); y **sin tarjeta cargada en Meta el número anda igual** (recibís y respondés dentro de las 24 h), lo único que no vas a poder es **iniciar** una conversación con una plantilla. No publicamos precios de Meta porque cambian y varían por país: mirá su tabla de tarifas. _Verificado contra la documentación de Meta el 04/09/2026._
- ⚠⚠ **AVISO DE COSTO — 1 DE OCTUBRE DE 2026, MENSAJES DE SERVICIO PAGOS (cambio de Meta).** Hoy responder en texto libre dentro de la ventana de 24 h es gratis. Desde el **1 de octubre de 2026** Meta cobra **por mensaje** esas respuestas, a la **misma tarifa que las plantillas de utilidad y autenticación de cada país** y **sin descuento por volumen**. ⚠ Ese mismo día Meta también empieza a cobrar **las plantillas de utilidad que respondés dentro de una ventana abierta**, que hoy son gratis. ⚠ **La ventana de 24 h NO se elimina**: sigue existiendo, se abre y se reinicia con cada mensaje del cliente y sigue gobernando _si podés_ mandar texto libre — lo que cambia es que deja de ser gratis. **Sigue gratis** la ventana de **72 h** de punto de entrada gratuito (anuncios de clic a WhatsApp y botones de Facebook/Instagram). Meta publica las tarifas por país **antes del 1 de septiembre de 2026**, y desde el **1 de agosto de 2026** su propio agente de IA se cobra por tokens (US$ 2 por millón). **Esto no cambia lo que cobra Connect**: los mensajes se los pagás a Meta directo, a su precio, y nosotros no le sumamos nada encima. _Re-verificado contra la documentación de Meta el 04/09/2026 («Upcoming pricing updates for Meta Business Agent, service and utility messages»)._