Security Analytics
Repackages your traffic logs into an attacker-fingerprint and mitigation view: how much traffic was allowed versus mitigated (blocked by a firewall rule or rate limit), a time series, the worst-offending source IPs / ASNs / countries / user-agents / paths / hosts / rules, and a tail of the most-recently mitigated requests. The numbers line up with the traffic metrics surface because both read the same traffic_logs data over the same scope and window.
A request counts as mitigated when its firewall action or rate-limit action was blocked; everything else is allowed. When a request is blocked by both, it is attributed to the firewall only, so allowed + mitigated_firewall + mitigated_ratelimit sums to total.
This endpoint requires the security_analytics plan entitlement and the traffic-inspector read permission. Callers on a plan without the entitlement receive 403.
Query parameters
time_range string
Window preset. One of
30m, 1h, 6h, 12h, 24h, 7d, 30d, or custom. Default 24h. Unknown values fall back to 24h.from, to string (RFC 3339)
Required when
time_range=custom — the explicit start and end of the window. to must be after from. Ignored for the presets.endpoint_uuid string (uuid)
Restrict the analysis to a single endpoint (its
uuid).host, path, method, source_ip, asn, country, ua, browser, os string
Drill-down filters. Pass a dimension to pivot the whole report onto that value — e.g.
source_ip=203.0.113.42 or country=US. browser / os match the derived label set (Chrome, Safari, iOS, Windows, …). Multiple dimensions combine with AND.<dim>_op string
Optional operator for each drill dimension, e.g.
path_op=starts_with. Free-text dimensions (host, path, ua) accept equals, not_equals, contains, starts_with, ends_with, in, not_in; enumerable dimensions (method, source_ip, asn, country, browser, os) accept equals, not_equals, in, not_in. Defaults to equals when omitted.Deprecated: endpoint_id (the old name of this filter; it takes the endpoint's uuid) is still accepted until the sunset. Send endpoint_uuid; sending both for different objects is a 400 id_uuid_mismatch.
Response (200 OK)
window object
The resolved window:
{start, end, time_range} (start/end are timestamps; time_range echoes the requested preset).totals object
{total, allowed, mitigated_firewall, mitigated_ratelimit, mitigated_total, mitigation_rate}. Counts over the window; mitigation_rate is mitigated_total / total (0–1).series object
Dense, aligned time series:
{labels, allowed, mitigated_firewall, mitigated_ratelimit}. Every array is the same length (one entry per bucket, zeros included). The bucket interval is chosen from the window size.top object
Top offenders per dimension:
{source_ips, asns, countries, user_agents, paths, hosts, rules, browsers, operating_systems, high_risk_ips}. Each is an array (top 10) ranked by mitigated then total. Standard dimensions emit {value, total, mitigated, mitigation_rate}; asns add a numeric asn; rules emit {value, rule_uuid, kind, hits} where kind is firewall or rate_limit; rule_uuid is the firewall policy's or the rate-limit rule's uuid. high_risk_ips lists the source IPs with the worst IP-reputation score in the window (up to 10, worst first) as {value, total, spam_score, mitigated, mitigation_rate}, spam_score being 0–100 (higher is worse); requests without a reputation score are left out. Every dimension is a list, [] when empty.recent_mitigated array
The latest ~20 mitigated requests. Each:
{uuid, rule_uuid, request_ts, source_ip, country, host, path, method, status_code, action, rule_name, spam_score, ip_health} where uuid is the traffic-log entry, action is firewall or rate_limit, and rule_uuid is the rate-limit rule's uuid on rate_limit rows (null otherwise).Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
400 Bad Request
Invalid time range (e.g.
custom with a missing or non-ordered from/to), or endpoint_id and endpoint_uuid naming different endpoints (id_uuid_mismatch).401 Unauthorized
Missing auth.
403 Forbidden
The active account's plan lacks the
security_analytics entitlement, or the member lacks traffic-inspector read permission.Request — mitigation overview, last 24h
curl "https://api.ngris.com/v1/traffic/security-analytics?time_range=24h" \
-H "X-API-KEY: <your_api_key>"
Request — drill into one source IP
curl "https://api.ngris.com/v1/traffic/security-analytics?time_range=7d&source_ip=203.0.113.42" \
-H "X-API-KEY: <your_api_key>"
Response — 200 OK
{
"window": {
"start": "2026-06-14T12:00:00Z",
"end": "2026-06-15T12:00:00Z",
"time_range": "24h"
},
"totals": {
"total": 18420,
"allowed": 17234,
"mitigated_firewall": 980,
"mitigated_ratelimit": 206,
"mitigated_total": 1186,
"mitigation_rate": 0.0644
},
"series": {
"labels": ["12:00", "13:00", "14:00"],
"allowed": [712, 690, 745],
"mitigated_firewall": [41, 38, 52],
"mitigated_ratelimit": [8, 9, 11]
},
"top": {
"source_ips": [
{"value": "203.0.113.42", "total": 420, "mitigated": 418, "mitigation_rate": 0.9952}
],
"asns": [
{"value": "AS15169 GOOGLE", "asn": 15169, "total": 120, "mitigated": 90, "mitigation_rate": 0.75}
],
"countries": [
{"value": "US", "total": 9200, "mitigated": 410, "mitigation_rate": 0.0446}
],
"user_agents": [],
"paths": [
{"value": "/wp-login.php", "total": 380, "mitigated": 380, "mitigation_rate": 1.0}
],
"hosts": [],
"rules": [
{"value": "Block login bruteforce", "rule_uuid": "019c32cb-35d7-786f-b2c5-d108951e23d8", "kind": "firewall", "hits": 612}
],
"browsers": [
{"value": "Other", "total": 990, "mitigated": 820, "mitigation_rate": 0.8283}
],
"operating_systems": [],
"high_risk_ips": [
{"value": "203.0.113.42", "total": 420, "spam_score": 92, "mitigated": 418, "mitigation_rate": 0.9952}
]
},
"recent_mitigated": [
{
"uuid": "019ba303-954b-796c-bf40-f33a26697f74",
"rule_uuid": null,
"request_ts": "2026-06-15T11:59:02Z",
"source_ip": "203.0.113.42",
"country": "US",
"host": "app.example.com",
"path": "/wp-login.php",
"method": "POST",
"status_code": 403,
"action": "firewall",
"rule_name": "Block login bruteforce"
}
]
}
Was this helpful?