Metrics alerts
Watch a saved Metrics chart and run your own Python or webhook when a value crosses a threshold or changes sharply.
A Metrics alert watches one saved chart and tells your automations when something changed: a topic doubled week over week, API failures passed 20 a day, a brand's refund requests jumped. The alert only decides when. What happens next is up to a Python event handler or a webhook listening to the metric_alert event: post to Slack, email a team lead, open a ticket, or anything else Python can do.
The easiest way to set one up is to ask Copilot, for example: "Alert us in Slack when any topic in the Topics report grows more than 25% week over week, as long as it had at least 20 conversations." Copilot creates the chart if needed, tests the rule on recent weeks, creates the alert and writes the handler. Everything is also available through MCP tools (list_metric_alerts, create_metric_alert, test_metric_alert, ...) and the REST API. On the Metrics page, a bell on a chart shows its alerts and their state.
How a check works
Each alert has a period: hour, day, week (Monday to Monday) or month, in the alert's timezone.
- When a period closes, the alert waits
delayMinutes(default 60) so late classification and indexing land. - It runs the chart for that period:
{{from}}and{{to}}are the period's start and end, and{{bucket}}is the period. Change conditions also run the period before, as the baseline. - It reads
valueColumnfrom the result. WithsplitBy, each value of that column (each topic, channel or brand) is its own series. Without it, the whole result is one series. Rows that share a series are summed, so a chart with daily rows still yields a weekly total. - It compares each series with the condition and with what was firing after the previous check.
- If any series started or stopped meeting the condition, it publishes one
metric_alertevent listing those series. A series that keeps firing is not repeated, so a handler hears about a problem once and again when it clears.
A new alert checks for the first time after the current period closes. businessIds limits the chart to some businesses; empty means every business.
Conditions
| Type | Fires while | Fields |
|---|---|---|
threshold | The value is above (>) or below (<) a number | operator (above, below), value |
change | The value moved by at least percent and/or absolute vs the previous period (both if both set) | direction (increase, decrease, either), percent, absolute, minBaseline |
every_check | Always. Every check publishes every series with its value and previous-period baseline | none |
- A series missing from one period counts as 0 there, which suits counts.
- A
percentchange is never met when the previous period was 0. Useabsoluteto catch something new. minBaselineignores series whose previous period was below it.every_checkkeeps no state. Use it when Python should decide, for example an anomaly check against your own history kept in the organization store.
Choosing rules that stay quiet
An alert is only useful if people act on it. A flat "+10% week over week" rule fires constantly: on one ordinary week of a large account it matched 229 of 613 brand-and-topic series, mostly small numbers moving by chance.
- Set a floor. Combine
percentwithabsoluteand aminBaseline, such as +25% and +10 conversations from at least 20. In the same week that cut 229 matches to 53. - Alert on shares when volume moves. During a sale every count grows. A chart column like "damaged-item conversations as a share of all conversations" only rises when the problem does.
- Use thresholds for rare, serious things. Legal threats, adverse reactions or devices overheating:
thresholdabove0on a daily period. - Test before saving.
test_metric_alert(orPOST /rest/v1/metric-alerts/test) replays a rule over up to 12 recent periods and shows each check that would publish. Tune until it fires only when someone should act.
The event
Handlers read context["args"]["metric_alert"]. Webhooks receive the same object under args.metric_alert. Both have no conversation.
| Field | Description |
|---|---|
alert_id | The alert |
alert_name | Its name |
chart | id, title, report_id and url (opens the report on the Metrics page) |
value_column | The column watched |
split_by | The split column, or None |
condition | The condition, with snake_case keys (min_baseline) |
period | unit, timezone, start, end, and previous_start/previous_end for the baseline (None for thresholds) |
business_ids | Businesses the chart ran over; empty means all |
checked_at | When the check ran |
firing_count | Series firing after this check, including ones that were already firing |
series_total | How many series this event covers. series holds at most 500 of them |
series | The series that changed state (every series for every_check), each with key, value, baseline, change_abs, change_pct and state (firing, resolved or checked) |
key is the split value, or None without a split. change_pct is None when the baseline is 0.
{
"alert_id": "6f1c…",
"alert_name": "Topic spikes",
"chart": {
"id": "…",
"title": "Conversations by topic",
"report_id": "…",
"url": "https://app.octocom.ai/organization/acme/metrics?report=…"
},
"value_column": "conversations",
"split_by": "topic",
"condition": {
"type": "change",
"direction": "increase",
"percent": 25,
"absolute": 10,
"min_baseline": 20
},
"period": {
"unit": "week",
"timezone": "Europe/Vilnius",
"start": "2026-11-08T22:00:00.000Z",
"end": "2026-11-15T22:00:00.000Z",
"previous_start": "2026-11-01T22:00:00.000Z",
"previous_end": "2026-11-08T22:00:00.000Z"
},
"business_ids": [],
"checked_at": "2026-11-15T23:03:12.000Z",
"firing_count": 1,
"series_total": 1,
"series": [
{
"key": "damaged-items",
"value": 412,
"baseline": 301,
"change_abs": 111,
"change_pct": 36.88,
"state": "firing"
}
]
}Handlers scoped to every business receive every alert. A handler limited to specific businesses receives only alerts whose businessIds is exactly one of its businesses. For an alert over several businesses, the webhook's business field and Python's context["business"] name a business of your organization only so helpers work; read business_ids to see what the alert covered. See Reacting to Metrics alerts for a Slack example.
To try a handler without waiting for a real alert, pass test_metric_alert's eventArgs to test_event_handler as {"metric_alert": ...}.
Status and history
Every alert reports a status:
state | Meaning |
|---|---|
not_checked | No check has run yet |
ok | Checked; nothing is firing |
firing | At least one series meets the condition (firingSeries) |
error | The last check failed; lastError says why |
inactive | Switched off |
A failed check is retried after 15 minutes, up to three times per period, and a check that never finishes (for example during a release) runs again 30 minutes later. After 10 failures in a row the alert switches itself off; switching it back on clears the error. Common causes are a renamed result column or chart SQL that times out.
Checks that published an event are kept for 90 days (get_metric_alert, GET /rest/v1/metric-alerts/{alertId}/events).
Changing what an alert watches (chart, columns, condition, period, timezone, delay or businesses) clears its firing state, so the next check reports from scratch. Renaming or switching it off does not.
Limits
- Alerts watch charts in shared reports only. Personal reports stay private.
- Up to 100 alerts per organization.
- Each check runs the chart once, plus once for a change baseline, with a 20-second limit per query. Checks run in the background, a few at a time, so a slow chart delays only its own alerts. Keep alert charts aggregated to the period, like any report chart.
- Viewing and testing alerts needs permission to view metrics. Creating, changing and deleting them needs permission to edit shared reports (
reports:writefor API keys, Modify settings in MCP).