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

# Alerts — anatomy

> The alert definition, the tag-driven trigger model, the metric catalog, and how it all fits together.

**Alerts** (Signals) raise instances when entities of interest appear, then notify and let
you act. This reference documents the full model. For the user guide, see
[Signals → Alerts](/en/signals/alerts).

## The tag-driven model

This is the key concept: **an alert triggers on tags, not on a raw metric threshold**.

```
metric threshold  ──(tagging rule)──►  tag on entities  ──(alert watches tag)──►  alert instance
```

```mermaid theme={null}
flowchart TB
  A["Metric Threshold"] -->|Tagging Rule| B["Tag on Entities"]
  B -->|Alert Watches Tag| C["Alert Instance Raised"]
```

* The **metric → threshold** logic lives in [tagging rules](/en/developers/tagging-rules/overview)
  (a metric condition tags the matching entities).
* An **alert** then watches for entities carrying those tags, within a perimeter and at a
  check level, and notifies.

So "alert me when days-of-stock ≤ 7" is expressed as: a tagging rule that tags low-stock
items, plus an alert that watches that tag.

## Alert definition

An `alerts` row has:

| Field                      | Meaning                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `name`                     | Display name.                                                                                   |
| `category` / `subcategory` | Classification (e.g. `INVENTORY` / `STOCK`).                                                    |
| `rules`                    | The tag-based trigger — see [Rules & perimeter](/en/developers/alerts/rules-and-perimeter).     |
| `scope`                    | The perimeter (stores / brands / products / taxonomies / collections).                          |
| `destination`              | Notifications — see [Notifications & actions](/en/developers/alerts/notifications-and-actions). |
| `isActive`                 | Whether the alert is evaluated.                                                                 |

```json theme={null}
{
  "name": "Low Stock Critical Products",
  "category": "INVENTORY",
  "subcategory": "STOCK",
  "rules": { "operator": "AND", "tagRules": [ { "tagId": "<uuid>", "mode": "INCLUDE" } ], "checkLevel": "PRODUCT" },
  "scope": { "storesIds": ["<uuid>"], "brandIds": ["<uuid>"] },
  "destination": { "frequency": "DAILY", "mediums": ["EMAIL"], "recipientIds": [] },
  "isActive": true
}
```

## The metric catalog

Metrics live in a separate `alert_metrics` catalog (referenced by tagging-rule metric
conditions). Each metric is `GLOBAL` (shared) or `ORG`-scoped, has a `kind`
(`precomputed_column`, `aggregation`, `time_windowed_aggregation`, `formula`, `composite`),
a calculation `body`, a `grain`, and an output. The standard metrics:

| Metric                                       | Measures                           |
| -------------------------------------------- | ---------------------------------- |
| `CURRENT_STOCK_LEVEL`                        | Current stock.                     |
| `GROSS_SALES_VALUE` / `GROSS_SALES_QUANTITY` | Sales value / units.               |
| `GROSS_SALES_VALUE_PREVIOUS`                 | Previous-period sales (for trend). |
| `FORECASTED_SALES_QUANTITY`                  | Forecast demand.                   |
| `INVENTORY_TURN_OVER_RATE`                   | Turnover rate.                     |
| `DAYS_OF_STOCK`                              | Days of cover at current velocity. |
| `RISK_SCORE`                                 | Intelligence-layer risk.           |
| `UNACTIONED_RECOMMENDATIONS_COUNT`           | Open recommendations.              |
| `SALES_TREND_PERCENT`                        | Sales trend %.                     |

<Note>
  The catalog attributes (`scope`, `kind`, `body`, `grain`) are populated at the
  data-platform/seed level — they are part of the stored metric definition, not the
  app-side create form (which only sets `category`, `subcategory`, `metricName`,
  `description`, `selectors`).
</Note>

<Note>
  These metrics are consumed by [tagging-rule metric conditions](/en/developers/tagging-rules/conditions),
  which is where the operator (incl. percentiles) and threshold are set. Alerts then watch
  the resulting tags.
</Note>

## Lifecycle

An alert is just active or not (`isActive`). Each evaluation produces **instances** with
their own lifecycle — see [Instances & runs](/en/developers/alerts/instances-and-runs).