Skip to main content

​
Usage & delivery anomaly alerts

Three signals tell you a CPaaS account is heading toward trouble before the invoice does: the SMS delivery rate collapsing (usually a carrier or route problem), outbound message volume surging (usually a compromised API key or a bot-driven SMS-pumping run), and spend climbing past what the account ever spends (bill shock in the making). This page covers the self-serve alert rules you point at those metrics — one rule per metric, either a hard threshold (“delivery below 95%”) or an anomaly mode that learns your own baseline and reacts to a sharp deviation without you naming a number.

​
1. The three metrics

​
2. Two rule modes

A threshold rule compares a fixed numeric condition against the metric over a lookback window — “delivery rate below 95% over the last 3 days”, “spend at or above $500/day over the last 7 days”. You name the comparator and the number. An anomaly rule drops the numbers entirely: Orbit scores the metric against roughly four weeks of your own daily history and fires when the latest day deviates sharply from that learned baseline — a collapse for delivery, a surge for volume or spend. Pick anomaly when you don’t know what “normal” looks like yet, or when a hard number would need a per-customer tuning pass. Threshold remains the right choice when you have an SLO in writing.

​
3. Create a rule

Rules are managed over /api/v1/usage/alert-rules. Threshold example:
Anomaly example (no comparator, no threshold):
Per-tenant limits and defaults: 50 rules per account, window 1–30 days (default 7), one notification channel today — the in-app notification feed with a direct link to the metric page. Writes need an owner, admin, or developer role; reads are available to any authenticated member. PATCH /usage/alert-rules/:id accepts the same fields minus metric/mode (those are fixed at creation), and DELETE /usage/alert-rules/:id removes it. A threshold rule can’t be edited into a state with no comparator or no threshold.

​
4. What fires, and the smart-buffered throttle

Two things decide when the platform actually lands a notification on your feed instead of silently updating the rule status:
  1. Edge-triggered. A rule notifies when it transitions from healthy into breach — not on every evaluation tick while it stays breached.
  2. Cooldown-gated re-fire. If the breach persists past cooldown_hours, one fresh notification goes out (with the cooldown start re-stamped), keeping a stuck-at-the-line metric from ringing your feed every ten minutes.
The fired event lands in the account’s notification feed with the rule name, the value at fire time (e.g. “Outbound message volume looks anomalous — the latest daily reading (4,832) deviates sharply from its recent baseline”), and a direct link to the metric — read them via GET /usage/alert-rules/events (newest first, 50 kept). The rule’s own last evaluation result (ok / breached / insufficient_data) and the value are returned on GET /usage/alert-rules, so a dashboard card can render them without extra calls.

​
5. Evaluate now, and insufficient data

POST /usage/alert-rules/evaluate triggers your account’s rules on demand — handy when wiring the rule into a dashboard widget or smoke-testing a new rule before leaving it armed. Evaluation is also run on a scheduled sweep against every account that defined at least one rule, so threshold and anomaly checks fire even while nobody has the dashboard open. insufficient_data means exactly that: a metric with too little history (your first couple of days on the metric), zero observations in the lookback window, or a resolution hiccup. It never fires — a degraded signal reports “we couldn’t judge”, never “breached”. A breach tells you where to act. The durable pairing for the spike-shaped metrics (volume, spend surges) is to add a hard ceiling that stops the burn until a human can look: set a per-channel spend cap or a spend-percentage rule on Billing → Alerts alongside the anomaly rule, so the spike informs while the cap enforces. Delivery drops usually want the opposite — investigate the route and pause a campaign, not clamp it.