# Uso e limites

`GET /v1/usage`

GET /v1/usage dá o consumo do período: `used`, `included`, `remaining`, `policy` (block|queue) e um `breakdown` por origem (`api`, `contact`, `device`). ⚠ **Regra do tráfego do celular (Coexistence):** `used = api + contact`; o tráfego `device` (o que o dono manda pelo celular) é mostrado mas **NÃO consome o plano**. O limite POR NÚMERO (`monthlyMessageLimit`) conta **só `api`**. Por número: `/v1/connections/:id/usage` e `/v1/usage/by-connection`; sobrevenda informativa: `/v1/accounts/oversubscription`.

## Exemplos

### cURL

```bash
curl https://api.waiaconnect.com/v1/usage \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# Public plan (no message cap): included and remaining are null.
# → { "used": 89, "included": null, "remaining": null, "policy": "block",
#     "breakdown": { "api": 0, "contact": 89, "device": 62 },
#     "breakdownNote": "used = api + contact; device does not count" }
# Only a custom plan with an agreed quota returns integers: "included": 25000, "remaining": 24911
```

### 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();
// Public plans have no message cap: included/remaining are null (a custom plan returns integers).
console.log(u.used, "/", u.included ?? "no cap"); // 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);
// Public plans have no message cap: included/remaining are null (a custom plan returns integers).
echo $u["used"] . " / " . ($u["included"] ?? "no cap"); // 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()
# Public plans have no message cap: included/remaining are None (a custom plan returns integers).
print(u["used"], "/", u["included"] if u["included"] is not None else "no cap")  # device is shown but not billed
```

## Notas

- ⚠ **Quatro limites diferentes, que não se misturam.** (1) **O do plano:** os planos públicos não têm teto de mensagens, então `included` e `remaining` chegam em **`null`** e `policy` não tem sobre o que agir; só um plano sob medida com cota pactuada devolve inteiros (e aí `QUOTA_EXCEEDED`). `used` mede tudo igual. (2) **O seu, por número:** `monthlyMessageLimit`, que você define com `PATCH /v1/connections/:id`; conta só `api` e, ao esgotar, dá `CONNECTION_QUOTA_EXCEEDED`. (3) **A velocidade da API:** 600 pedidos por minuto por chave; passar disso dá `RATE_LIMITED` (429, com `Retry-After`). (4) **Os da Meta**, no ponto seguinte.
- Os buckets são agregados em UTC; o `timezone` da conta é devolvido só para você montar a legenda.
- ⚠⚠ **OS LIMITES DA META SÃO OUTRA COISA, E SÃO ELES QUE VÃO TE FREAR.** Nós não pomos teto de mensagens; a Meta põe dois, e eles não se misturam. (1) **CONTATOS** — com quantas pessoas DIFERENTES você inicia conversa em 24 h: **250 → 2.000 → 10.000 → 100.000 → sem limite**, e sobe com verificação do negócio, volume e qualidade. ⚠ **Desde 7 de outubro de 2025 esse limite é por PORTFÓLIO empresarial, não por número**: todos os números do mesmo portfólio COMPARTILHAM a cota. Se você administra números de vários clientes, dimensione com isso em mente. (2) **RITMO** — com que velocidade saem: até **80 mensagens/segundo** por número na Cloud API (até **1.000** com o upgrade automático), e **20/segundo fixo** para um número em Coexistence; passar disso devolve o `130429` da Meta. Do nosso lado **você não perde mensagens por ir mais rápido**: a fila as absorve e as drena, com novas tentativas e idempotência. _Verificado contra a documentação da Meta em 30/08/2026._
- Os limiares de 70/90/100% chegam por webhook (`usage.threshold_reached` / `connection.usage_threshold_reached`). ⚠ O de CONTA é relativo à cota do plano, então **sem teto ele não dispara**; o POR NÚMERO (`connection.usage_threshold_reached`) sim, porque esse limite é você quem define.
- **O que a Meta cobra é à parte de tudo isto:** veja [O que a Meta cobra e o que o WAIA Connect cobra](https://waiaconnect.com/pt/docs/meta-pricing-change).