Usage and limits

GET /v1/usage

Building with AI? Connect it to your account over MCP: it checks your setup, creates webhooks and templates with your confirmation and writes the code for you. See how →

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. Plan numbers: includedNumbers, activeNumbers (registered right now), extraNumbersThisCycle (extra numbers of the cycle in numbers/month, prorated by day, with decimals), extraEstimateUsd and nextChargeEstimate (date, baseUsd, extraUsd, totalUsd). Scale includes 30 numbers and adds USD 3 per extra number per month, prorated by day and charged with the next renewal; with fewer than 30 the plan stays at USD 99.

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

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
$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

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

⚠ Four different limits, and they don't mix. (1) The plan's: public plans have no message cap, so included and remaining come back as null and policy has nothing to act on; only a custom plan with an agreed quota returns integers (and then QUOTA_EXCEEDED). used still measures everything. (2) Yours, per number: monthlyMessageLimit, which you set with PATCH /v1/connections/:id; it counts only api and, once used up, returns CONNECTION_QUOTA_EXCEEDED. (3) The API's speed: sending, per number (Coexistence 20/s, Cloud API 80/s) and per account; everything else, 600 requests per minute per key; going over returns RATE_LIMITED (429, with Retry-After) — see «Rate limits». (4) Meta's, in the next point.

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 quota, so with no cap it never fires; the PER-NUMBER one (connection.usage_threshold_reached) does, because you set that limit.

What Meta charges is separate from all of this: see What Meta charges and what WAIA Connect charges.