Alerts — instances & runs

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:

{
  "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.
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.

{
  "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.

Runs share the same observable shape (status, trigger type, structured logs, stats) as ingestion and tag evaluation runs.

API integration

API recipes

Platform & data model

Decision layer (reference)

Operations & infrastructure

Ingestion specs (reference)

Workflows (reference)

Tagging rules (reference)

Alerts (reference)

Alerts — instances & runs

Alert instances

Evaluation runs

​Alert instances

​Evaluation runs

Alert instances

Evaluation runs