API reference Resources
Alerts
Alerts raised by policies.
2 operations
List alerts
What a policy's Alert action or a justified override raised, newest first.
Query parameters
The filter expression, e.g. all;outcome~in~undetermined;mode~in~monitor.
The first segment is the join (all or any); each later segment is field~op~values, with op one of in, nin, before, after and values separated by commas. Fields: outcome, mode, severity, policy, machine, service, interaction, at. A malformed segment is ignored; a field this list does not have is a 400 naming it.
Where the previous page stopped. Opaque; an unreadable one starts over.
Rows wanted. Clamped to 200.
action or justification: narrow to what raised the alert. Anything else is a 400 naming it.
true also lists alerts whose machine or connection was removed. They are kept as audit history and are left out of the default list.
Response200
The decider's clock — what the list is ordered and filtered by, because that is what an operator means by this week.
passed, alerted, blocked or undetermined.
`undetermined` is not a flavour of `passed`. It says nothing looked, where passed says something looked and was satisfied. A reader that renders them the same has reproduced the placebo failure the outcome was added to make visible.
What raised it: action (the policy's Alert action) or justification (a justified override). Every alert has one.
When the server recorded the alert, by the server's clock. Retention ages alerts by this time, not by decided_at.
The support code a stopped person was given, where one was shown.
Every alert the filter matched, across all pages, not only this one.
Pass back as cursor for the next page. null means this was the last.
Errors
- 400
The filter names a field or value this surface does not have
- 401
No valid session
- 403
Caller lacks alerts:read in this workspace
One alert, by its id
A 404 for an unknown id and for one belonging to another workspace, which is deliberately not a 403: a 403 would confirm the id exists somewhere, which is the one thing a probe wants to learn, and the rest of this API already answers a cross-workspace id this way.
Path parameters
Response200
The decider's clock — what the list is ordered and filtered by, because that is what an operator means by this week.
passed, alerted, blocked or undetermined.
`undetermined` is not a flavour of `passed`. It says nothing looked, where passed says something looked and was satisfied. A reader that renders them the same has reproduced the placebo failure the outcome was added to make visible.
What raised it: action (the policy's Alert action) or justification (a justified override). Every alert has one.
When the server recorded the alert, by the server's clock. Retention ages alerts by this time, not by decided_at.
The support code a stopped person was given, where one was shown.
The alert's severity: info, low, medium, high or critical. It is the severity the policy's Alert action set, or the outcome's default where the policy named none.
inline, policy or engine. Carried verbatim: a reader must render a value it does not recognise rather than folding the field into a boolean.
The connection whose sync ingested the interaction this alert was made about; null on every alert a machine's interaction produced, and on every alert whose interaction is gone.
The run to open, and null once retention has taken it.
Read, not derived from `engine_type`. A run is swept at 30 days by default and an alert is kept for a year, so the link is dead for most of an alert's life; a page that offers it anyway sends the reader to a 404, and the evidence beside it (engine_score, engine_labels) is still true.
The interaction this judged. null for a server-side decision whose observation arrives later on a different request, and for a fail-open where there may be none at all — not a sign that anything is missing.
The person's own words on a justified alert; null on every other.
monitor or enforce, as the policy stood when it decided. A monitor alert stopped nothing. null only on some older alerts.
The policy's name as it stands now, for a sentence. null where the policy has been deleted — the version is still named, so the row degrades to an id rather than to nothing.
The exact version that decided, not the one that is current. An author may have rewritten the rule since; this is what makes the row evidence rather than a pointer at whatever the policy says today.
Why, in the decider's own words. Never customer content.
Which engine returned no verdict, on an undetermined. Names an engine.
Errors
- 401
No valid session
- 403
Caller lacks alerts:read in this workspace
- 404
No such alert in this workspace