Skip to main content

​
Insights Alerts console operator guide

The Insights → Alerts console is the central place to manage self-serve alert rules over your cross-pillar metrics and usage signals. From one surface you can author rules, preview them against recent data, run on-demand evaluations, and triage fired alerts. Rules are org-scoped and tenant-configurable: you choose the metric, the trigger, and the threshold. Evaluation is read-only over your data; the only writes are the rule state and the in-app notification it fires.

​
Where to open the console

Open Insights → Alerts in the dashboard, or go directly to /insights/alerts. The console has three panels:
  • Rules table — every KPI alert rule with its current value, last status, and enabled state.
  • Create-rule dialog — choose a metric, trigger, comparator, and threshold.
  • Fired alerts feed — the last 50 breach events with a deep link to the metric.
KPI alerts live on this page. Usage and delivery anomaly rules live on the companion page at Insights → Usage alert rules (/insights/usage-alert-rules). Both surfaces share the same notification channel and evaluation lifecycle.

​
KPI alert vs usage-anomaly alert vs scheduled report

Use KPI alerts to guard customer experience and AI cost. Use usage-anomaly alerts to guard the transport layer and your bill. Use scheduled reports for regular summaries that do not need a threshold.

​
Author a rule

​
Create a KPI alert rule

  1. From /insights/alerts, click Create rule.
  2. Name the rule.
  3. Pick the Metric: CSAT, NPS, CES, LLM spend, or AI containment.
  4. Pick the Trigger:
    • Threshold — compare the metric to a fixed bound.
    • Anomaly — compare the latest reading to the metric’s own 28-day learned baseline.
  5. For threshold rules, set the Condition (comparator) and numeric Threshold.
  6. Set the Window (days) the threshold aggregates over (1–90; default 7). Anomaly rules still show a window but compare daily against the baseline.
  7. Set the Cooldown (hours) between repeat notifications while a breach persists (1–720; default 24).
  8. Toggle Enabled and save.

​
Create a usage-anomaly alert rule

Use the same flow on /insights/usage-alert-rules. The metric list is SMS delivery rate, outbound message volume, and spend; threshold windows are 1–30 days.

​
Preview against recent values

The create/edit dialog renders the last 30 days of the metric as a sparkline or value table. For threshold rules, a horizontal line shows your chosen bound. For anomaly rules, the preview highlights the latest daily reading and the learned baseline band so you can see whether the rule would have fired recently.

​
Notification shaping

When a rule breaches, it fires into the in-app Notification Center with:
  • Severity: warning
  • Title: KPI alert: <rule name> or Usage alert: <rule name>
  • Body: a human-readable sentence such as “CSAT is 74.2%, below the 80% threshold over the last 7d.”
  • Deep link: a direct link to the metric surface (for example, /insights/surveys, /insights/llm-spend, /insights/containment, or /insights for usage alerts)
Notifications are deduplicated by cooldown: a rule that stays breached re-notifies at most once per cooldown_hours. The first transition into breach always notifies immediately. The only configured notification channel is the dashboard bell. Poll the fired-event feed to integrate alerts into external systems.

​
Mute, snooze, and rule versioning

  • Mute a rule: toggle Enabled off. Disabled rules are not evaluated and do not fire notifications.
  • Snooze repeat notifications: raise cooldown_hours so a sustained breach re-pages less often. The rule still evaluates and shows its status.
  • Rule versioning: rules are single-version today. Editing a rule updates it in place and records an audit log entry. There is no revert history. To preserve a configuration before changing it, create a new rule with the old values first.

​
Rate limits on evaluation

The alert-rule endpoints follow the standard analytics rate-limit classes:
  • Read endpoints — GET /analytics/kpi-alert-rules, GET /analytics/kpi-alert-rules/events, and the equivalent usage alert-rule GET endpoints are rate-limited as authenticated reads.
  • Write endpoints — POST, PATCH, DELETE, and POST .../evaluate for both KPI and usage alert rules are rate-limited as authenticated writes.
On-demand evaluation via Evaluate now runs the same evaluator as the scheduled sweep; use it to test a rule or re-check immediately.