> ## 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 — instances & runs

> The alert instance lifecycle, what an instance records, the evaluation-run model, and an example.

## Alert instances

Each time an alert matches, an **instance** is raised. Its user-facing lifecycle is tracked
separately from the immutable raised record:

| Status         | Meaning                                           |
| -------------- | ------------------------------------------------- |
| `pending`      | Newly raised; no action yet.                      |
| `acknowledged` | A user has seen it (records who/when).            |
| `resolved`     | Handled (records who/when + an optional comment). |
| `archived`     | Hidden from the active list.                      |

An instance records what was matched — for example:

```json theme={null}
{
  "alert_id": "<uuid>",
  "alert_value": 85.5,
  "trigger_type": "THRESHOLD_APPROACHING",
  "approach_percentage": 92,
  "tags": ["low-stock", "critical"],
  "perimeter_results": {
    "shop_ids": [
      { "id": "<shop>", "productIds": [ { "id": "<product>", "variants": [ { "id": "<variant>", "value": 2 } ] } ] }
    ],
    "brandIds": ["<brand>"]
  }
}
```

* `alert_value` — the matched value.
* `trigger_type` — see [trigger types](/en/developers/alerts/rules-and-perimeter#trigger-types).
* `approach_percentage` — how close to the threshold (for `THRESHOLD_APPROACHING`).
* `perimeter_results` — the matched entities, by perimeter level. The key casing
  reflects the stored shape as-is (e.g. `shop_ids` alongside `brandIds`).

## Evaluation runs

Alerts are evaluated by an **alert evaluation run** — manual, scheduled, or via API. A run
evaluates active alerts (or a specified subset), **creates** instances for new matches, and
**resolves** instances that no longer match.

| Field         | Meaning                                                                     |
| ------------- | --------------------------------------------------------------------------- |
| `status`      | `PENDING → RUNNING → SUCCESS / FAILED`.                                     |
| `triggerType` | `MANUAL`, `SCHEDULED`, or `API`.                                            |
| `alertIds`    | Specific alerts to evaluate (null = all active).                            |
| `stats`       | `{ alertsEvaluated, instancesCreated, instancesResolved, durationMs }`.     |
| `logs`        | Structured entries (`DEBUG`/`INFO`/`WARN`/`ERROR`), capped at 5000 per run. |

```json theme={null}
{
  "status": "SUCCESS",
  "triggerType": "MANUAL",
  "stats": { "alertsEvaluated": 2, "instancesCreated": 3, "instancesResolved": 1, "durationMs": 4523 }
}
```

Because a run both creates and resolves, the active instance list stays in sync — an issue
that clears is resolved automatically on the next run.

<Note>
  Runs share the same observable shape (status, trigger type, structured logs, stats) as
  [ingestion](/en/developers/ingestion) and
  [tag evaluation](/en/developers/tagging-rules/runs-and-examples) runs.
</Note>