# Metric alerts ## Tools Alerts are personal — each person sets their own, and nobody configures them for anyone else. They are checked only after a scheduled refresh (the `cadence` of `update_dashboard`), never after one you trigger, and arrive in the bell and by email. | Tool | What it does | | |---|---|---| | [`list_metric_alerts`](#list_metric_alerts) | List metric alerts | Read-only | | [`set_metric_alerts`](#set_metric_alerts) | Set metric alerts | Destructive write | ## list_metric_alerts `Read-only` Your own metric alerts on a dashboard (or one widget), beside each widget's eligibility: `kind` (timeseries | kpi | categorical | unavailable, with `reason`; categorical = a single-series bar chart over categories, each bar a series, thresholds only), its `seriesKeys` with display labels, and `anomalyOk` (whether `unusualMove`, anomaly detection, may be set; `anomalyReason` says why not). `allWidgets` is the All widgets row. `scheduledRefresh` false means no alert can fire until update_dashboard's `cadence` turns a schedule on: alerts are checked only after SCHEDULED refreshes, never after refresh or explore_dashboard. Alerts are personal — you never see or set anyone else's. Guests cannot use alerts. Requires view access. ## set_metric_alerts `Destructive write` Set YOUR alerts on one widget, or (widgetId omitted) on every eligible widget of the dashboard — REPLACING that row's triggers, so re-send the ones to keep (list_metric_alerts shows them). `triggers` is required; send {} to CLEAR the row — only your alerts; other people's are untouched. Four optional triggers, each watching EVERY series on the widget: `threshold` {above?, below?} — a closed period crosses the line (the first check only records where it stands); on a single-series bar chart over categories (not dates), the only trigger, each bar checked every scheduled run; `absoluteChange` {amount > 0} and `relativeChange` {pct > 0} — a closed period moved at least that much from the one before, up OR down; `unusualMove` {sensitivity: high | medium | low} — anomaly detection: the move is in the tail of the series' own history (a time series, or a KPI with a date column, with enough history). The All widgets row (widgetId omitted) takes only `relativeChange` (every time series and KPI, never a categorical bar chart) and `unusualMove`; on a widget where you set the same kind yourself, the widget's own setting and delivery win. `delivery` immediate | digest applies to the whole row (default: kept, else immediate for a widget, digest for all widgets). Checked only after SCHEDULED refreshes, once a period has ended. Alerts arrive in the bell and by email. Caps: 200 subscriptions per person per workspace, 200 people per dashboard. Guests cannot set alerts. Requires view access.