Usage & delivery anomaly alert rules

Define org-scoped alert rules that watch the signals that move a CPaaS account: SMS delivery rate, outbound message volume, and spend. When the metric breaks your threshold — or deviates sharply from its own learned baseline — the rule fires an in-app notification the whole team sees in the dashboard’s Notification Center. Rules are read-only over your account. Evaluation aggregates your already-persisted message and billing-ledger rows; the only writes are alert-rule state and the notification it fires. No outbound traffic ever results from a rule. This complements In-dashboard notifications and the Notification Center (the surface rules notify on) and Per-API-key usage budgets and threshold alerts (a browser-local tripwire; everything on this page is org-scoped and shared with your team).

Endpoints

All endpoints share the standard { "data": ..., "meta": ... } envelope and are tenant-scoped.

Method	Path	Purpose
`GET`	`/usage/alert-rules`	List your rules with evaluator state (`last_status`, `last_value`, `last_evaluated_at`, `last_fired_at`)
`POST`	`/usage/alert-rules`	Create a rule (returns `201`)
`PATCH`	`/usage/alert-rules/{id}`	Update name, comparator, threshold, window, cooldown, or `enabled`
`DELETE`	`/usage/alert-rules/{id}`	Delete a rule
`GET`	`/usage/alert-rules/events`	Fired-alert feed, newest first, capped at the last 50 events
`POST`	`/usage/alert-rules/evaluate`	Evaluate all of this tenant’s rules now (returns `{"tenantId", "rulesEvaluated", "breached", "fired"}`)

A tenant can hold up to 50 rules.

Auth requirements

Reads (GET ..., GET .../events) — a valid API key/JWT whose scopes include usage:read.
Writes and evaluate-now (POST, PATCH, DELETE, POST .../evaluate) — additionally require an org role of owner, admin, or developer. The audit log records create/update/delete with the acting user.

Rule shapes

Each rule targets one metric, using one of two modes.

Metrics

`metric`	Label	Unit	Direction the rule guards
`sms_delivery_rate`	SMS delivery rate	percent (e.g. `95.7`)	Guards a drop (routing/carrier trouble)
`outbound_message_volume`	Outbound message volume	count	Guards a surge (pumping misuse)
`spend`	Spend	USD	Guards a surge (bill shock)

Delivery rate and volume are computed over your outbound messages with the same status filters the dashboard’s delivery KPI card uses, and spend is aggregated from wallet-ledger debits excluding admin adjustments — so an alert fires on exactly the numbers the dashboard shows.

Threshold mode (default)

Compares the metric’s value over a trailing window against a fixed number.

comparator: one of gt, gte, lt, lte
- lt / lte — “must stay above X” (e.g. delivery rate below 95%)
- gt / gte — “must stay below X” (e.g. volume above 10k/day, spend above $100)
threshold: a finite number on the metric’s native unit
window_days: the trailing window the threshold aggregates over, 1–30 (default 7)

A threshold rule cannot exist without both a comparator and a threshold — create and update both reject it (422).

Anomaly mode

Compares the newest complete UTC day against a learned 28-day baseline using a z-score classifier. You set no threshold — “unusual for your account” is the trigger. For delivery rate it detects a downward drop; for volume and spend, an upward spike (the metric on volume/spend rules is inverted internally so a spike registers the same way). Anomaly rules must not carry comparator/threshold at create time (they are ignored); pass only mode: "anomaly" plus window_days, cooldown_hours, notify_channels, enabled.

Field reference (create / update body)

Field	Type	Constraints	Default
`name`	string	1–160 chars	required
`metric`	enum	one of the three metrics above	required
`mode`	enum	`threshold`, `anomaly`, `any`	`threshold`
`comparator`	enum	`gt`, `gte`, `lt`, `lte`	required in threshold mode
`threshold`	number	finite	required in threshold mode
`window_days`	integer	1–30	7
`notify_channels`	array	subset of `["in_app"]`	`["in_app"]`
`cooldown_hours`	integer	1–720	24
`enabled`	boolean		`true`

notify_channels currently accepts only in_app. Alerts surface through the existing dashboard notification channel (the bell / Notification Center); email or webhook fan-out is not yet on this surface.

The fired event lifecycle

A scheduler-driven sweep continuously evaluates every tenant that has at least one rule, and POST /usage/alert-rules/evaluate runs the same evaluation on demand for your tenant. On every evaluation tick, each enabled rule updates its runtime fields (last_evaluated_at, last_status, last_value) — even in a breach. An event is appended to your fired-alert feed (max 50, newest first) and a notification pushed only when:

the rule’s status transitions into breached, or
it stays in breach and the cooldown_hours re-notify window (default 24h) has elapsed since the last notification.

While the rule stays in breach but inside the cooldown, state still updates but no new event/notification is emitted — the same signal does not re-page you for 24 hours. A metric that cannot be resolved (no data in the window, or a provisioning gap) is reported as insufficient_data and never fires a false alert.

Event payload

Each entry in GET /usage/alert-rules/events:

Field	Meaning
`id`	Unique event id
`rule_id`, `rule_name`	Which rule fired
`metric`	The rule’s metric
`status`	`breached` (cleared states are not events)
`value`	Metric value at fire time (`null` when insufficient data)
`threshold`, `comparator`, `mode`	The rule’s configured trigger at fire time
`message`	Human-readable sentence (“SMS delivery rate is 82.4%, below the 95% threshold over the last 7d.”)
`deep_link`	Dashboard path to the metric surface (currently `/insights`)
`fired_at`	ISO-8601 timestamp

Poll GET /usage/alert-rules/events to consume alerts from an API integration, or open the Notification Center in the dashboard.

Where alerts land in the dashboard

A firing rule reuses the in-app notification channel: it appears in the bell dropdown and the Notification Center with severity warning, titled Usage alert: <your rule name>, with the threshold/anomaly sentence as the body and a deep link to the Insights page. See In-dashboard notifications and the Notification Center for triage/read/dismiss semantics.

Example: delivery-failure-rate alert

Create a rule that fires when SMS delivery rate over the trailing week falls below 95%, and re-fires at most once a day while it stays breached:

curl -X POST https://api.orbit.devotel.io/api/v1/usage/alert-rules \
  -H "Authorization: Bearer dv_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SMS delivery rate below 95%",
    "metric": "sms_delivery_rate",
    "mode": "threshold",
    "comparator": "lt",
    "threshold": 95,
    "window_days": 7,
    "cooldown_hours": 24
  }'

Response (201):

{
  "data": {
    "id": "b2e2a9a1-…",
    "name": "SMS delivery rate below 95%",
    "metric": "sms_delivery_rate",
    "metric_label": "SMS delivery rate",
    "unit": "percent",
    "direction": "higher_is_better",
    "metric_path": "/insights",
    "mode": "threshold",
    "comparator": "lt",
    "threshold": 95,
    "window_days": 7,
    "notify_channels": ["in_app"],
    "enabled": true,
    "cooldown_hours": 24,
    "last_evaluated_at": null,
    "last_status": null,
    "last_value": null,
    "last_fired_at": null,
    "created_at": "2026-08-27T12:00:00.000Z",
    "updated_at": "2026-08-27T12:00:00.000Z",
    "created_by_user_id": "user_…"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-27T12:00:00.000Z" }
}

Evaluate now (optional — the scheduler sweep also evaluates it on its own cadence):

curl -X POST https://api.orbit.devotel.io/api/v1/usage/alert-rules/evaluate \
  -H "Authorization: Bearer dv_live_sk_…"

{ "data": { "tenantId": "acme", "rulesEvaluated": 1, "breached": 1, "fired": 1 }, "meta": { … } }

Then read the fired feed:

curl https://api.orbit.devotel.io/api/v1/usage/alert-rules/events \
  -H "Authorization: Bearer dv_live_sk_…"

{
  "data": {
    "items": [
      {
        "id": "evt_…",
        "rule_id": "b2e2a9a1-…",
        "rule_name": "SMS delivery rate below 95%",
        "metric": "sms_delivery_rate",
        "status": "breached",
        "value": 82.4,
        "threshold": 95,
        "comparator": "lt",
        "mode": "threshold",
        "message": "SMS delivery rate is 82.4%, below the 95% threshold over the last 7d.",
        "deep_link": "/insights",
        "fired_at": "2026-08-27T12:00:00.000Z"
      }
    ],
    "total": 1
  },
  "meta": { … }
}

A mode: “anomaly” variant — pick up when the newest day’s delivery rate deviates sharply from the learned 28-day baseline, without fixing a threshold:

{ "name": "Delivery-rate anomaly", "metric": "sms_delivery_rate", "mode": "anomaly" }

Troubleshooting

422 says “comparator is required for a threshold rule”. Pass both comparator and threshold whenever the rule is threshold mode (create, and any update on a threshold rule; mode defaults to threshold). A rule’s last_status reads insufficient_data. The metric could not be resolved in the window — usually zero outbound messages (or wallet debits, for spend rules) in the window. Evaluation reports no value rather than firing on a fabricated 0%. The rule fires fewer notifications than expected. That is cooldown semantics: while a rule stays in breach, it re-notifies only once per cooldown_hours (default 24h); new breach transitions always notify immediately. You want email or webhook instead of the dashboard notification. The only configured channel today is the dashboard notification (notify_channels: ["in_app"]). Poll the fired-event feed to integrate alerts into your own systems.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Usage & delivery anomaly alert rules

Usage & delivery anomaly alert rules

Endpoints

Auth requirements

Rule shapes

Metrics

Threshold mode (default)

Anomaly mode

Field reference (create / update body)

The fired event lifecycle

Event payload

Where alerts land in the dashboard

Example: delivery-failure-rate alert

Troubleshooting

​Usage & delivery anomaly alert rules

​Endpoints

​Auth requirements

​Rule shapes

​Metrics

​Threshold mode (default)

​Anomaly mode

​Field reference (create / update body)

​The fired event lifecycle

​Event payload

​Where alerts land in the dashboard

​Example: delivery-failure-rate alert

​Troubleshooting

Usage & delivery anomaly alert rules

Endpoints

Auth requirements

Rule shapes

Metrics

Threshold mode (default)

Anomaly mode

Field reference (create / update body)

The fired event lifecycle

Event payload

Where alerts land in the dashboard

Example: delivery-failure-rate alert

Troubleshooting