# Consumo e limiti

`GET /v1/usage`

GET /v1/usage restituisce il consumo del periodo: `used`, `included`, `remaining`, `policy` (block|queue) e un `breakdown` per origine (`api`, `contact`, `device`). ⚠ **Regola del traffico del telefono (Coexistence):** `used = api + contact`; il traffico `device` (quello che il titolare manda dal cellulare) viene mostrato ma **NON consuma il piano**. Il limite PER NUMERO (`monthlyMessageLimit`) conta **solo `api`**. Per numero: `/v1/connections/:id/usage` e `/v1/usage/by-connection`; sovrallocazione informativa: `/v1/accounts/oversubscription`.

## Esempi

### 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
```

## Note

- ⚠ **Quattro limiti diversi, che non si mescolano.** (1) **Quello del piano:** i piani pubblici non hanno un tetto di messaggi, quindi `included` e `remaining` arrivano a **`null`** e `policy` non ha niente su cui agire; solo un piano su misura con una quota concordata restituisce numeri interi (e lì `QUOTA_EXCEEDED`). `used` misura tutto comunque. (2) **Il tuo, per numero:** `monthlyMessageLimit`, che imposti tu con `PATCH /v1/connections/:id`; conta solo `api` e, quando si esaurisce, dà `CONNECTION_QUOTA_EXCEEDED`. (3) **La velocità dell'API:** 600 richieste al minuto per key; se la superi ottieni `RATE_LIMITED` (429, con `Retry-After`). (4) **Quelli di Meta**, nel punto seguente.
- I bucket si aggregano in UTC; il `timezone` dell'account viene restituito solo perché tu possa comporre la didascalia.
- ⚠⚠ **I LIMITI DI META SONO UN'ALTRA COSA, E SONO QUELLI CHE TI FERMERANNO.** Noi non ti mettiamo un tetto di messaggi; Meta sì, te ne mette due, e non si mescolano. (1) **CONTATTI** — con quante persone DIVERSE avvii una conversazione in 24 h: **250 → 2.000 → 10.000 → 100.000 → senza limite**, e si sale con la verifica dell'attività, il volume e la qualità. ⚠ **Dal 7 ottobre 2025 quel limite è per PORTAFOGLIO aziendale, non per numero**: tutti i numeri dello stesso portafoglio CONDIVIDONO la quota. Se gestisci numeri di più clienti, dimensiona tenendone conto. (2) **RITMO** — quanto velocemente partono: fino a **80 messaggi/secondo** per numero sulla Cloud API (fino a **1.000** con l'aumento automatico), e **20/secondo fissi** per un numero in Coexistence; se li superi ricevi il `130429` di Meta. Da parte nostra **non perdi messaggi andando più veloce**: la coda li assorbe e li smaltisce, con nuovi tentativi e idempotenza. _Verificato sulla documentazione di Meta il 30/08/2026._
- Le soglie del 70/90/100% arrivano via webhook (`usage.threshold_reached` / `connection.usage_threshold_reached`). ⚠ Quella di ACCOUNT è relativa alla quota del piano, quindi **senza tetto non scatta**; quella PER NUMERO (`connection.usage_threshold_reached`) sì, perché quel limite lo imposti tu.
- **Quello che addebita Meta è a parte rispetto a tutto questo:** vedi [Cosa addebita Meta e cosa addebita WAIA Connect](https://waiaconnect.com/it/docs/meta-pricing-change).