# Usage and limits

`GET /v1/usage`

GET /v1/usage gives the period consumption: `used`, `included`, `remaining`, `policy` (block|queue) and a `breakdown` by origin (`api`, `contact`, `device`). ⚠ **The phone-traffic rule (Coexistence):** `used = api + contact`; `device` traffic (what the owner sends from the phone) is shown but does **NOT consume the plan**. The PER-NUMBER limit (`monthlyMessageLimit`) counts **only `api`**. Per number: `/v1/connections/:id/usage` and `/v1/usage/by-connection`; informational oversubscription: `/v1/accounts/oversubscription`.

## Examples

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

## Notes

- ⚠ **No message cap (flat rate):** `included` and `remaining` come back as **`null`** and `policy` has nothing to fire on — what defines your plan is how many NUMBERS you connect, not how many messages you send. `used` still measures everything. A bespoke plan with an agreed allowance returns integers for both.
- Buckets aggregate in UTC; the account `timezone` is returned only so you can caption it.
- ⚠⚠ **META'S LIMITS ARE A DIFFERENT THING, AND THEY ARE THE ONES THAT WILL STOP YOU.** We put no message cap on you; Meta puts two, and they don't mix. (1) **CONTACTS** — how many DISTINCT people you start a conversation with in 24 h: **250 → 2,000 → 10,000 → 100,000 → unlimited**, raised by business verification, volume and quality. ⚠ **Since 7 October 2025 that limit is per business PORTFOLIO, not per number**: every number in the same portfolio SHARES the allowance. If you manage numbers for several customers, size with this in mind. (2) **PACE** — how fast they go out: up to **80 messages/second** per number on the Cloud API (up to **1,000** with the automatic upgrade), and a fixed **20/second** for a Coexistence number; exceeding it returns Meta's `130429`. On our side **you don't lose messages by going faster**: the queue absorbs them and drains, with retries and idempotency. _Verified against Meta's documentation on 2026-08-30._
- The 70/90/100% thresholds reach you by webhook (`usage.threshold_reached` / `connection.usage_threshold_reached`). ⚠ The ACCOUNT one is relative to the plan's allowance, so **with no cap it never fires**; the PER-NUMBER one does, because that limit is yours.
- 🔴 **THERE ARE TWO PAYMENTS HERE, AND THEY ARE SEPARATE.** (1) **You pay WAIA Connect for the infrastructure**: your plan, per connected number, with no message cap. (2) **You pay Meta for the messages**, with your own card added to your own Meta account — we neither charge it nor see it. ⚠ The three costliest confusions: **the free trial is OURS, not Meta's** (Meta charges from the first message of the first day); **Meta charges PER MESSAGE delivered, not per conversation** (conversation-based pricing existed until **1 July 2025** and Meta retired it — estimating per conversation comes out short); and **with no card in Meta the number still works** (you receive, and you reply within 24 hours), the one thing you cannot do is **start** a conversation with a template. We do not publish Meta's prices because they change and vary by country: see their rate card. _Verified against Meta's documentation on 2026-09-04._
- ⚠⚠ **COST NOTICE — 1 OCTOBER 2026, SERVICE MESSAGES BECOME PAID (Meta's change).** Today a free-form reply inside the 24-hour window is free. From **1 October 2026** Meta charges **per message** for those replies, at the **same rate as utility and authentication templates in each market** and **with no volume discount**. ⚠ On that same date Meta also starts charging for **utility templates sent in reply inside an open window**, which are free today. ⚠ **The 24-hour window is NOT removed**: it still exists, it opens and resets with each customer message and it still governs _whether_ you can send free-form text — what changes is that it stops being free. The **72-hour** free-entry-point window (click-to-WhatsApp ads and Facebook/Instagram buttons) **stays free**. Meta publishes per-country rates **by 1 September 2026**, and from **1 August 2026** its own AI agent is billed by token (US$ 2 per million). **This does not change what Connect charges**: you pay Meta directly for messages, at Meta's price, and we add nothing on top. _Re-verified against Meta's documentation on 2026-09-04 ("Upcoming pricing updates for Meta Business Agent, service and utility messages")._