Preview Metric Alert
POST
/v1/traffic/alerts/preview
Evaluates a proposed alert rule against current traffic without creating it, so you can answer "what's the level right now, and would this fire?" before arming the rule. It computes the metric over the trailing window_seconds using the exact same formula the alert evaluator worker uses, so the preview can't disagree with a live rule.
The request body is the same shape as Create Alert (an alert-rule object). Only metric, operator, threshold, window_seconds, and the optional endpoint_uuid are used; name, notify_channels, and the other create fields are not required for a preview. Unknown JSON fields are rejected.
Requires the endpoints:read permission on the active account (the one listing and reading alerts needs), and no entitlement: saving the rule with Create Alert needs endpoints:write and the metric_alerts entitlement.
Request body
One of: request_rate (req/s), error_rate_pct (% of 4xx+5xx), p95_latency_ms, p99_latency_ms, bandwidth_in_bps, bandwidth_out_bps.
Comparison applied to compute would_fire_now. One of: >, >=, <, <=.
Threshold value in the metric's native unit (req/s, percent, ms, bytes/s).
Aggregation window the metric is computed over. Must be between 60 and 86400 (1 minute to 24 hours).
Optional. Scope the metric to a single endpoint in your account. Omit to evaluate account-wide.
Other create-time fields (name, description, cooldown_seconds, enabled, notify_channels) are accepted in the body but ignored by the preview. Note that unrecognized field names cause a 400.
Response (200 OK)
A point-in-time snapshot — not historical fire-frequency.
Echoes the requested metric.
Echoes the requested operator.
Echoes the requested threshold.
Echoes the requested window.
The metric's value over the trailing window_seconds right now, in the metric's native unit.
true if current_value satisfies operator against threshold right now.
A fixed explanatory string clarifying that this is a point-in-time snapshot, not historical fire-frequency.
Errors
Invalid JSON, an unknown field in the body, or window_seconds outside 60–86400.
The supplied endpoint_uuid doesn't match an endpoint in your tenant.
No active account, not a member, or missing the endpoints:read permission.
The metric could not be evaluated.
curl -X POST "https://api.ngris.com/v1/traffic/alerts/preview" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"metric": "error_rate_pct",
"operator": ">",
"threshold": 1.0,
"window_seconds": 300,
"endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e"
}'
import requests
r = requests.post(
"https://api.ngris.com/v1/traffic/alerts/preview",
headers={"X-API-KEY": "<your_api_key>", "Content-Type": "application/json"},
json={
"metric": "p99_latency_ms",
"operator": ">",
"threshold": 500,
"window_seconds": 300,
},
).json()
print(f"current={r['current_value']} would_fire={r['would_fire_now']}")
{
"metric": "error_rate_pct",
"operator": ">",
"threshold": 1.0,
"window_seconds": 300,
"current_value": 0.42,
"would_fire_now": false,
"note": "current_value is the metric over the last window_seconds right now; would_fire_now compares it to the threshold. Point-in-time snapshot, not historical fire-frequency."
}