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

# Group Spend Alerts

> Monitor spend summed across every subscription line item whose feature belongs to a group, configured via API

Group spend alerts monitor the **usage-based spend summed across every line item on a subscription whose feature belongs to a given group**, for example every metered feature grouped under "Compute" or "Storage". This scope is useful when several distinct meters should count toward one shared budget, and is configured through the API.

## Prerequisite: Assign Features to the Group

A group's spend total only includes line items whose meter is backed by a **feature that has this group set as its `group_id`**. A feature with no group, or a different group, never contributes to this alert, even if it's on the same subscription.

> [!WARNING]
>
> If none of a subscription's line items resolve to a feature in the configured group, the group total is `0` and the alert never fires. Confirm every feature you expect to count is assigned to the group before troubleshooting a group alert that isn't triggering.

**1. Create a group**

Create a group with **Entity type** set to **Feature**. See [Creating a group](https://docs.tirdad.ai/docs/product-catalogue/groups/create.md).

**2. Assign each feature to the group**

For every feature whose usage should count toward this alert, set its `group_id` to the group created above. See [Feature grouping](https://docs.tirdad.ai/docs/product-catalogue/groups/feature-grouping.md).

## Configuring via API

A group alert is always scoped to one subscription. The same group can have a different configuration (or no configuration) on a different subscription.

```json theme={null}
{
  "entity_type": "group",
  "entity_id": "group_01K7YQ0000GROUPID000001",
  "parent_entity_type": "subscription",
  "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
  "config": {
    "alert_enabled": true,
    "warning":  { "threshold": "400", "condition": "above" },
    "critical": { "threshold": "800", "condition": "above" }
  }
}
```

```bash cURL theme={null}
curl -X POST 'https://api.tirdad.ai/v1/alerts/setting' \
  -H 'x-api-key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "group",
    "entity_id": "group_01K7YQ0000GROUPID000001",
    "parent_entity_type": "subscription",
    "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG",
    "config": {
      "alert_enabled": true,
      "warning":  { "threshold": "400", "condition": "above" },
      "critical": { "threshold": "800", "condition": "above" }
    }
  }'
```

> [!NOTE]
>
> `parent_entity_type` and `parent_entity_id` are mandatory for group alerts. Unlike subscription-level alerts, a group alert cannot be unscoped.

## Managing Alert Settings

### Viewing current configuration

**1. Identify the alert setting**

Query by `entity_type`, `entity_id`, and `parent_entity_id` to find the setting for this group and subscription.

**2. Send the request**

```bash theme={null}
curl -X POST 'https://api.tirdad.ai/v1/alerts/setting/search' \
  -H 'x-api-key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "group",
    "entity_id": "group_01K7YQ0000GROUPID000001",
    "parent_entity_id": "subs_01K7YQ8ZR4M3V2N1XA9C6D0EFG"
  }'
```

### Changing thresholds

**1. Build the complete config**

Include every threshold you want to keep, not just the one you're changing.

> [!WARNING]
>
> The update replaces `config` entirely. It does not merge with what's stored. Send every threshold you want to keep on each update; a threshold left out is cleared.

**2. Send the request**

`PUT /v1/alerts/setting/:id` with the complete desired `config`.

### Removing a threshold

**1. Drop the threshold from config**

Build the update payload with that threshold omitted and the others included as-is.

**2. Send the request**

`PUT /v1/alerts/setting/:id` with the trimmed `config`.

### Disabling alerts

**1. Set alert\_enabled to false**

Build the update payload with `config.alert_enabled` set to `false`.

**2. Send the request**

`PUT /v1/alerts/setting/:id` with the updated `config`.

## Webhooks

| Event | Fires when |
| - | - |
| `subscription.group_spend.threshold_reached` | Spend crosses a threshold |
| `subscription.group_spend.threshold_recovered` | Spend recovers to `ok` |

> [!NOTE]
>
> Only groups actually touched by an event's usage are re-evaluated for that event.

## Use Cases

* **Shared budgets across meters**: Alert once for combined spend across several related metered features (e.g. all compute-related meters) instead of tracking each individually
* **Product-line budgets**: Group features by product line and alert per line, independent of how many individual meters make it up
* **Consolidating noisy line items**: Roll up several low-value, high-frequency line items into one group threshold instead of alerting on each separately

## Related

* [What Are Spend Alerts?](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/what-are-spend-alerts.md): all three alert scopes, shared validation, and the full API reference
* [Subscription spend alerts](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-spend-alerts.md): monitor the whole subscription
* [Line item spend alerts](https://docs.tirdad.ai/docs/subscriptions/how-to-configure-spend-alerts/how-to-configure-subscription-line-item-spend-alerts.md): monitor a single line item
* [Groups: Feature grouping](https://docs.tirdad.ai/docs/product-catalogue/groups/feature-grouping.md): assign features to a group
* [Webhooks](https://docs.tirdad.ai/docs/webhook/webhooks): endpoint setup, payload signatures, and retry behavior


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.