Skip to main content
A standard cost alert evaluates a single number—the running total of the subscription’s draft invoice. A grouped cost alert instead breaks that total into per‑group subtotals and evaluates each group independently, firing once for every distinct group that crosses a threshold.
Grouped cost alerts are a paid add‑on and aren’t available on all Orb plans. Contact your Orb account team to learn more.
Use a grouped cost alert when a single Orb subscription represents many of your customers, seats, projects, or workloads. Group spend by an event property to get a signal per group:
  • Per‑seat spend caps in usage‑based seat pricing (grouping_keys: ["seat_id"]).
  • Per‑end‑user budgets when you resell or wrap Orb (grouping_keys: ["customer_id"]).
  • Per‑model, per‑region budgets in inference pricing (grouping_keys: ["model", "region"]).
Grouping is configured at creation time on a cost_exceeded alert. It cannot be changed afterward; create a new alert to change the grouping. A subscription (or plan) can have at most 3 grouped cost alerts.

​
Configuration

​
Which prices contribute

Within the alert’s currency (and any price_filters), every usage‑based and license price on the draft invoice contributes to the per‑group subtotals. Fixed fees and composite prices are excluded—a fixed fee has no usage to group by, and a composite price is derived from other line items rather than from an independent metric.
For license prices, grouped subtotals are computed as a per‑group quantity × rate and do not account for per‑license pool drawdowns. The grouped value is a usage‑attribution estimate at the marginal rate, not a reconciliation of the invoice. On license‑priced plans, the sum of per‑group subtotals will not match the line item’s billed amount, which reflects the aggregate overage after drawdowns. Set thresholds accordingly.

​
Per‑group threshold overrides

By default every group is evaluated against the same thresholds. threshold_overrides lets you tailor thresholds for specific groups—give an enterprise tenant a higher cap, or silence an internal test group entirely. Each override maps a specific combination of grouping_keys values to a list of thresholds that fully replaces the defaults for that group:
  • A non‑empty thresholds list replaces the default thresholds for that group.
  • An empty thresholds list silences that group—it never fires.
  • Groups without an override use the default thresholds.
An alert can have up to 50 threshold overrides. Overrides are only valid on subscription‑scoped alerts. Plan‑scoped alerts reject threshold_overrides, because the relevant group values vary from subscription to subscription.

​
Example

Create a subscription cost alert with POST /v1/alerts/subscription_id/{subscription_id} that fires at $500 per seat_id, ignores the platform fee, raises the cap for one seat, and silences an internal seat:

​
Cardinality limit

Because each distinct group is evaluated separately, grouping on a high‑cardinality property (for example a per‑event ID) can produce an unbounded number of groups. To protect evaluation, Orb caps a grouped alert at 1,000 distinct groups per evaluation. If a subscription exceeds that limit, Orb automatically disables the alert for that subscription and emits a subscription.alert_disabled webhook so you can react. Choose grouping keys with bounded cardinality (seats, tenants, models) rather than unbounded identifiers.

​
Webhooks

When groups cross a threshold, Orb batches all groups that fired in the same evaluation timeframe into one subscription.grouped_cost_exceeded webhook—rather than one webhook per group—with the timeframe window in the payload. A single webhook covers up to 1,000 groups, matching the cardinality limit above.