​

Spend alerts, burn rate, and the velocity-anomaly model

​

The three instruments, side by side

​

Velocity anomaly detection — the model

• Baseline — the average daily spend over the trailing 14 complete UTC days (today excluded). Manual operator wallet adjustments (admin_grant / admin_deduct rows and admin* references) are excluded from both sides, so bookkeeping never looks like usage.
• Today — spend so far in the current (incomplete) UTC day, extrapolated to a full-day rate: projected = today_spend / day_fraction_elapsed. The fraction is floored at one hour of the day, so a one-minute burst at 00:03 does not project to an absurd rate.

1. Absolute floor — the projected daily rate clears **$250/day** (25,000 cents). This gate falls first, and it is what keeps a tenant spending$0.10/day from generating a page when $0.30/day is a 3x surge.
2. Surge multiple — the projected rate reaches 10x the baseline daily average. A new tenant with no baseline history at all is treated as a cold-start surge the moment the projection clears the floor — there is no prior spend to compare against, and an instant $250/day projection for an org that never spent is itself the anomaly.

​

The anomaly ledger

• GET /api/v1/billing/spend-anomaly — the current evaluation. Returns the detected anomalies, the applied tunables (surge_multiplier, min_projected_daily_minor, baseline_days), and day_fraction_elapsed so you can re-derive any ratio yourself. Each newly detected channel also lands in the fraud-review queue for operators — deduplicated to one entry per (organization, channel, UTC day), so polling the endpoint can’t spam the queue.
• GET /api/v1/billing/spend-anomaly/ledger — the historical ledger of everything the detector has recorded for your organization (the dashboard poll and the continuous background sweep both write to it). Optional from/to ISO timestamps bound the window; limit is bounded to 500 (default 100), newest first. Every entry carries the channel, surge ratio, baseline/today/projected spend in minor units, any auto-mitigation applied, and the review’s triage status (open / triaged / dismissed / escalated) with its acknowledgement and resolution timestamps.

​

Mitigation — the self-expiring throttle

• high severity → throttle: the channel is clamped down to 10 sends or calls per minute. Legitimate low-volume traffic still flows; a toll-fraud pump is choked.
• critical severity → pause: the clamp is 0 per minute — every send or call on that channel is refused until the mitigation expires or you clear it.

• Min-only. It can only ever lower the effective per-minute cap the fraud guards enforce. It can never raise your own configured cap, so an anomaly can never weaken protection you already set.
• Self-expiring. Every mitigation record carries an expires_at, capped at 6 hours (and never longer than the rest of the UTC day). An automatic throttle must not linger on a false positive: when the record expires the guards ignore it and the channel reverts on its own — no revert job, no operator action.
• Tenant-clearable. You can clear an active mitigation early from the fraud-caps surface in the dashboard when you’ve confirmed the surge is legitimate (a real launch, a known campaign).

​

Escalation and incidents

• an incident snapshot anchored to your policy (open, pages_fired: 0), and
• the flattened plan — the ordered page timeline with total_pages, next_tick_at, and whether the policy is exhausted.

​

Example flows

{
  "name": "SMS daily spend guard",
  "threshold_type": "daily_spend",
  "threshold_value": 50000,
  "notify_emails": ["finance@example.com"],
  "action_on_hit": "notify",
  "cooldown_hours": 6
}

{
  "data": {
    "id": "alert_7f3c9a1b",
    "threshold_type": "daily_spend",
    "threshold_value": 50000,
    "action_on_hit": "notify",
    "enabled": true
  }
}

{
  "data": {
    "detected": true,
    "anomalies": [
      {
        "channel": "sms",
        "baseline_daily_minor": 4200,
        "today_spend_minor": 214000,
        "projected_daily_minor": 428000,
        "surge_ratio": 101.9,
        "severity": "critical"
      }
    ],
    "baseline_days": 14,
    "surge_multiplier": 10,
    "min_projected_daily_minor": 25000,
    "day_fraction_elapsed": 0.5
  }
}

{
  "data": {
    "entries": [
      {
        "id": "fr_2a91c4e8",
        "category": "spend_velocity_anomaly",
        "severity": "critical",
        "status": "open",
        "channel": "sms",
        "surge_ratio": 101.9,
        "baseline_daily_minor": 4200,
        "today_spend_minor": 214000,
        "projected_daily_minor": 428000,
        "auto_mitigation": {
          "mode": "pause",
          "channel": "sms",
          "max_per_min": 0,
          "ttl_seconds": 21600
        },
        "detected_at": "2026-09-04T11:58:20.000Z",
        "acknowledged_at": null,
        "resolved_at": null
      }
    ],
    "count": 1,
    "window": { "from": null, "to": null }
  }
}

​

Next steps

• Billing overview — the endpoint surface map.
• Wallets, credits, and charges — the ledger and the pause-gate semantics these instruments sit on.
• On-call and the escalation-policy model — rotations, page timelines, and the incident state machine behind the escalation bridge.
• On-Call API reference — the incident tick and transition endpoints an escalation plan drives.