Per-Agent Traffic Series

GET /v1/traffic/metrics/per-agent

Returns request volume bucketed over time and broken down by the serving agent across your active account. Powers the per-agent sparklines on the fleet page. The response is a shared x-axis (labels) plus one count series per agent (series), all aligned so each agent's array lines up index-for-index with the labels.

Bucket width is chosen automatically from the window: per-minute for a 1-hour range, per-hour up to 7 days, and per-day beyond that. The x-axis is dense — buckets with no traffic are present and zero-valued. Agents with no traffic in the window do not appear in series. Requests with no agent attribution (e.g. UDP session rows or edge-generated errors) are excluded.

Requires the traffic-inspector read permission on the active account.

Query parameters

time_range string
Window length. One of 5m, 1h, 24h, 7d, 30d, 90d. Defaults to 24h when omitted; unrecognized values also fall back to 24h.

Response (200 OK)

time_range string
The window string used (echoes the request, after defaulting).
labels array<string>
The shared, ordered x-axis bucket labels (e.g. hour-of-day or date), one per bucket from window start to end.
series object
Map of agent session id → array of request counts (int64), one entry per label and in the same order as labels. Only agents with traffic in the window are present. Empty object when there is no agent-attributed traffic.

Errors

400 Bad Request
Returned for an invalid time_range value.
401 Unauthorized
Missing auth.
403 Forbidden
No active account, not a member, or missing the traffic-inspector read permission.
Request
curl "https://api.ngris.com/v1/traffic/metrics/per-agent?time_range=24h" \ -H "X-API-KEY: <your_api_key>"
Python — total per agent
import requests r = requests.get( "https://api.ngris.com/v1/traffic/metrics/per-agent", params={"time_range": "24h"}, headers={"X-API-KEY": "<your_api_key>"}, ).json() for agent_id, counts in r["series"].items(): print(f"{agent_id}: {sum(counts)} requests over {len(r['labels'])} buckets")
Response — 200 OK
{ "time_range": "24h", "labels": ["00:00", "01:00", "02:00", "03:00"], "series": { "agent-7f3a9c": [120, 98, 76, 64], "agent-2b1e44": [40, 0, 12, 31] } }
Homepage Docs Dashboard Docs API Docs nvelox Dashboard
Iris