Skip to main content

​
Alert instances

Each time an alert matches, an instance is raised. Its user-facing lifecycle is tracked separately from the immutable raised record:
StatusMeaning
pendingNewly raised; no action yet.
acknowledgedA user has seen it (records who/when).
resolvedHandled (records who/when + an optional comment).
archivedHidden 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.
FieldMeaning
statusPENDING → RUNNING → SUCCESS / FAILED.
triggerTypeMANUAL, SCHEDULED, or API.
alertIdsSpecific alerts to evaluate (null = all active).
stats{ alertsEvaluated, instancesCreated, instancesResolved, durationMs }.
logsStructured 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.