The alerting pieces on Devotel Orbit already ship: a per-API-key usage budget in the dashboard drawer, tenant-set usage alert rules evaluated on the API, the anomaly ledger every detector writes to, route-quality thresholds per operator, KPI alerts on CSAT/NPS/CES, and scheduled reports for the weekly review. What was missing was one guide that composes them — which surface alerts on what, where each raise lands, and which tier of the program it belongs to. This is that guide. It builds a three-tier ladder (cost, volume, quality) out of the shipped pieces and closes with the runbook entry every tenant should pin when a usage alert fires.
1. Usage-layer alerting — what fires, to where
Usage-layer alerting covers the signals that move the wallet and the traffic counters: monthly spend per API key, outbound message volume, delivery rate, per-agent conversation depth, and the detector classes on the anomaly ledger. Two properties define how these alerts run on Orbit.
First, every threshold is tenant-set. The platform evaluates your limits on a schedule and notifies in-app; it does not pick values and it never reroutes or throttles outbound traffic on its own. A level-definition note for operators: outbound (MT) voice and messaging exit only through Devotel's own softswitch, so an alert always leaves the routing decision to the tenant — the inbound-only providers stay inbound-only and never carry the re-route.
Second, each raise lands in a defined home. A detector raise lands in the anomaly ledger at Insights → Anomalies with a per-day trendline; a threshold breach on a usage metric lands in the in-app notification feed with a link back to the metric; a KPI alert on CSAT/NPS/CES or LLM spend lands the same way from Insights → KPI Alerts; and a scheduled digest at Insights → Scheduled reports lands in email on a daily, weekly, or monthly cadence. Every surface above reads back the threshold its owner set, so the rule lives in one place and the alert carries the fired value, not a recomputed estimate.
2. The shipped surfaces, composed
Six published references cover the individual surfaces; this ladder uses all of them.
- Per-API-key budgets — the usage-budget guide walks the drawer's budget card and its API-level pair (
PUT /developer/budgets/{keyId}) end to end. The browser budget is a personal tripwire; the persisted per-key budget is the team-visible one, and both are advisory — blocking belongs to the monthly request quota. - Usage alert rules — Insights → Usage alert rules (
/insights/usage-alert-rules) is the self-serve editor over three usage metrics — delivery rate, outbound volume, and spend — with a threshold or anomaly mode, a window, and a cooldown between firings. - The anomaly ledger — usage and delivery anomaly detection explains the append-only ledger at Insights → Anomalies and its wallet-vs-webhook/inbound scope split; the module walkthrough maps the four detection surfaces (ledger, per-route DLR, LLM spend, route quality) end to end.
- Route-quality thresholds — Messages → Settings → Route quality bands each operator (MCC/MNC) by delivery rate, latency percentiles, and grey-route suspicion, with a manual "Check & notify" evaluation paging the in-app bell on each breached threshold.
- KPI alerts — Insights → KPI Alerts defines threshold and anomaly rules on the cross-pillar business KPIs — CSAT, NPS, CES, LLM spend, and AI containment — so a quality drop pages in-app rather than waiting for the next scheduled digest.
- Scheduled reports — the scheduled digests post covers the email digest surface that carries the recurring summary to recipients without dashboard seats, paired with the threshold alert for anything that can't wait a week. The deliverability benchmarks post grounds the volume-tier numbers in what receipts actually prove before you set a delivery-rate threshold.
3. The three-tier ladder
The ladder assigns every shipped surface to one tier by the question it answers, then layers tiers so a raise on one is never the only signal an operator reads.
Tier 1 — cost: per-key budgets and the spend governor
The cost tier bounds what a single integration can burn. Set a persisted per-key budget on Settings → API keys with at least the 50/80/100 alert ladder, pair it with the org-level usage-alert threshold so the whole team sees the tripwire, and let the LLM-spend cost governor bound AI conversation depth in the same way. The browser local budget stays as a personal earlier layer only. A 100%-of-budget badge tells the operator which key is about to trip, hours to weeks before it shows on the wallet.
Tier 2 — volume: delivery-rate and route-DLR thresholds
The volume tier guards what actually left the platform. Set a usage alert rule on delivery rate and outbound volume per channel, and read the per-route DLR-drop card on Insights → Deliverability as the statistical version of the same raise. When a route breaches, the operator response is a delivery fallback: drain the degraded provider × destination pairing and rotate it to a healthy operator while the baseline rebuilds. The thresholds stay tenant-owned both ways — the platform never re-routes on its own.
Tier 3 — quality: CSAT/NPS drop and containment breach
The quality tier guards what the customer experience looked like. Set a KPI alert on weekly CSAT (or NPS, or CES) with a comparator and a window, and let the anomaly ledger carry the detector-side raise for anything no threshold predicted. A CSAT drop below target lands in-app with a link straight to the metric, so the Tuesday problem shows up the same day rather than in the following Monday's digest. The scheduled reports surface still runs the digest for the review — the tier settles the boundary between recap (digest) and interrupt (alert).
Layer them and each raise reads against its neighbors: a cost raise with a quiet volume tier points at one runaway integration, not a provider drift; a quality raise with a clean delivery tier points at an agent or flow change, not a carrier fault; volume and quality raising together points at a route.
4. Runbook entry — what to do when a usage alert fires
Pin this sequence at the top of your on-call doc; each step names the surface the alert deep-linked to.
- Read the scope and fired value. The notification feed carries the rule that fired and the value at evaluation time. Open the linked surface — the anomaly ledger for detector raises, the deliverability card for route raises, the KPI surface for quality raises — and confirm whether the raise sits in wallet scope (a cost question) or webhook/inbound scope (a reliability and exposure question).
- Classify against the ladder. Cost-tier raise → check which key, channel, or agent burned; volume-tier raise → check which route and destination dropped; quality-tier raise → check the KPI's broken segment (one flow, one queue, one agent version).
- Cut the loop, using tenant-owned controls only. For a cost raise, raise or pause the per-key budget, rotate the leaked API key, or let the governor downshift; for a volume raise, drain the route toward the healthy operator; for a quality raise, roll back the agent version or fix the flow. Route-quality's Check & notify and the evaluate-now call on usage rules re-evaluate after the fix without waiting for the schedule.
- Move the row to resolved. On the anomaly ledger, triage status moves open → resolved on the row itself, so the ledger doubles as the queue. Keep high/critical wallet raises routed to on-call in-app, and let the daily digest or the weekly scheduled report carry the rest.
Each surface pairs with its own docs guide — the per-key budget guide, the usage-anomaly alert-rules guide, and the route-quality and KPI alert panels above — so the runbook stays in the tenant's vocabulary end to end.
Frequently asked questions
Which alert surfaces are tenant-configurable in Devotel Orbit?
All of them. Per-API-key budgets, usage alert rules, route-quality thresholds, KPI alerts on CSAT/NPS/CES, the usage-alert-rule cooldown, and scheduled reports accept tenant-set values. The only platform-wide detectors are the anomaly classes that raise into the ledger; thresholds stay tenant-owned either way.
Where does a usage alert land when it fires?
In the in-app notification feed, with a deep link back to the surface the breach belongs to. Detector raises land in the anomaly ledger. A scheduled digest lands in email. Alert routing is per tier — cost and volume raises page on-call, quality raises notify the CX channel.
How should we split alerts vs scheduled digests?
Alerts interrupt; digests recap. Anything that can't wait for the next review cadence gets an alert rule — a KPI threshold, a usage rule, a detector — and the scheduled report carries the recurring summary to recipients without dashboard seats. The two surfaces do different jobs, and the ladder uses both.
Does the platform ever reroute or throttle traffic on an alert?
No. Outbound voice and messaging exit only through Devotel's softswitch, and every threshold is advisory — the raise tells you a boundary passed; changing routing, pausing a key, or tightening a budget stays a tenant-owned decision. Inbound-only providers never carry the re-route.