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

# Alerts

> Watch an aggregate metric and send a webhook when it crosses a threshold or changes.

Alerts evaluate an aggregate metric on a schedule and notify your webhook when its state changes. Create and manage them from **Alerts** in the dashboard.

## Create an alert

Start with a name, the measure to evaluate, and an optional **Group by** dimension. Grouping evaluates the selected measure for each group; choosing **Single total** evaluates one total instead. You can also add filters to narrow the events the alert evaluates.

Only plain entity dimensions are available for grouping. Time, JSON, derived, and grain grouping are not supported.

### Choose a condition

| Condition      | Configure                              | Grouping      |
| -------------- | -------------------------------------- | ------------- |
| **Threshold**  | Measure, operator, and value           | Optional      |
| **Comparison** | Measure, direction, and change percent | Not available |

A threshold alert fires when a measured value matches its operator and value. A comparison alert checks whether a single total has increased or decreased by the chosen percentage, so remove grouping before selecting it.

### Set the schedule

**Evaluate every** controls how often the alert runs. You can choose 1, 5, or 15 minutes; 1, 6, or 12 hours; or 1 day.

**Look-back window** is how many minutes of data each evaluation looks at. It must be at least as long as the evaluation interval and at most 1 day (1,440 minutes).

## Delivery

A webhook URL is required for every alert. Carbon sends a JSON payload when an alert breaches, resolves, or becomes broken.

| Field            | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `alert`          | The alert `id` and `name`                                 |
| `alertUrl`       | The dashboard URL for the alert                           |
| `evaluatedAtMs`  | The evaluation time in milliseconds                       |
| `kind`           | `breach`, `resolve`, or `broken`                          |
| `observed`       | Observed values, each with a `value` and optional `group` |
| `firedGroups`    | Groups that newly breached, when applicable               |
| `resolvedGroups` | Groups that newly resolved, when applicable               |
| `spaceId`        | The space that owns the alert                             |
| `test`           | Present and `true` for a test delivery                    |

Use **Test** beside the webhook URL to send the current preview payload with `test: true`. The test is marked as a test delivery and does not create alert history.

## Statuses

| Status     | Meaning                                            |
| ---------- | -------------------------------------------------- |
| **OK**     | The alert is evaluating and has no active breach   |
| **Firing** | The alert is evaluating with an active breach      |
| **Broken** | Evaluation has stopped after an evaluation failure |

Edit a broken alert to reset its evaluation and resume it.

## Run history

Each alert keeps a run history of its most recent 50 evaluations. A run can be **OK**, **Breach**, **Error**, or **Insufficient data**.

Select a run to open its details, including the evaluation time, delivery state, error when present, changed groups, and the observed-value preview.

<Note>
  Each space can have up to 20 alerts.
</Note>