Create the rules, switch them on and off, and read what actually fired.
The two shapes
An alert watches one of two things, and they take different fields:
trigger_type | Needs | Fires when |
goal | goal_name | That goal converts |
traffic_spike | threshold | Traffic rises past the number |
traffic_drop | threshold | Traffic falls past it |
Sending the wrong pair is a 400 naming the field. The field the type does
not use is stored as null rather than left stale — so switching a goal alert
to a traffic one drops the goal name, and the row stays consistent with what
it claims to be.
threshold_mode is the part people get wrong
| What the number means | |
absolute | A count. "Fewer than 50 visitors this hour." |
percent_change | A percentage against the same hour last week. "Down 50% on last Tuesday at 09:00." |
For most sites percent_change is the one that works. An absolute threshold
on a site with a weekly rhythm fires every Saturday night and teaches everyone
to ignore it.
An alert belongs to the site, not to you
Any key with alerts:write can edit or delete any alert on a site it reaches.
That is deliberate, and it is the opposite of
notes, where only the author may edit. An alert is the
site's configuration — the person who set it up should not be the only one who
can switch it off at 3am. created_by is still recorded, so you can see who
did.
Editing is partial, and null means something
Send only what changes:
curl -X PATCH ".../alerts/$ALERT_ID" \
-H "Authorization: Bearer $TRUESTAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'Omitting a field keeps it; sending null clears it. The two are
different on purpose — a caller that meant to empty a field and silently got
the old value back would have no way to tell.
Deleting takes the history with it
The delivery rows cascade. Everything the alert ever fired disappears from history along with the rule.
When you want it to stop firing but keep the record, switch it off instead.
What fired, and what was heard
History is the other half. The important case is an alert that triggered and failed to send: the condition happened, the rule worked, and nobody was told. From the inbox that looks exactly like nothing happening.