> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withorb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grouped cost alerts

> Evaluate per‑group spend subtotals (e.g. per seat or tenant) instead of the single subscription invoice total.

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.

<Note>
  Grouped cost alerts are a paid add‑on and aren't available on all Orb plans. Contact your Orb account team to learn more.
</Note>

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

| Field                 | Required            | Description                                                                                                                                                                                                                                                    |
| --------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grouping_keys`       | Yes                 | One or more event property keys (up to 5, no duplicates) to group spend by. Subtotals are computed per distinct combination of these keys' values.                                                                                                             |
| `currency`            | Yes (when grouping) | The case‑sensitive currency or custom pricing unit to scope the alert to. Required whenever `grouping_keys` is set, since subtotals can't be summed across pricing units.                                                                                      |
| `price_filters`       | No                  | Restricts *which* prices contribute to the subtotals. Each filter matches on `price_id`, `item_id`, or `price_type` with an `includes` or `excludes` operator, combined with AND. For example, exclude a fixed platform fee so it doesn't inflate every group. |
| `threshold_overrides` | No                  | Per‑group threshold customization (see below).                                                                                                                                                                                                                 |

## 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.

<Note>
  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.
</Note>

## 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}`](/api-reference/alert/create-subscription-alert) that fires at \$500 per `seat_id`, ignores the platform fee, raises the cap for one seat, and silences an internal seat:

```json theme={null}
{
  "type": "cost_exceeded",
  "thresholds": [{ "value": "500.00" }],
  "grouping_keys": ["seat_id"],
  "currency": "USD",
  "price_filters": [
    { "field": "price_type", "operator": "includes", "values": ["usage"] }
  ],
  "threshold_overrides": [
    { "group_values": ["seat_enterprise"], "thresholds": [{ "value": "5000.00" }] },
    { "group_values": ["seat_internal"], "thresholds": [] }
  ]
}
```

## 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`](/integrations-and-exports/webhooks#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`](/integrations-and-exports/webhooks#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.