Traffic Metrics
Account-scoped traffic metrics over the requested time window — request count, error breakdown, bandwidth (in/out), latency percentiles, top endpoints, method/country distribution, and SLO data. Aggregated across every endpoint in your active account. For per-endpoint metrics, use /traffic/endpoints/{uuid}/metrics.
Useful for the dashboard's top summary widget. For real-time live values, prefer /traffic/metrics/realtime; for time-series buckets, use /traffic/history.
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. Unknown values fall back to 24h.endpoint_id string (uuid)
Optional. Restrict to a single endpoint by its UUID (alternative to the per-endpoint route). A UUID outside your account is ignored.
Response (200 OK)
A flat object. Key fields (not exhaustive):
total_requests int64
Total request count in the window.
error_rate number
Percentage (0–100) of requests with a 4xx/5xx status that were not firewall- or rate-limit-blocked.
average_response_time number
Mean latency in milliseconds (end-to-end: tunnel-server queue + agent + upstream).
median_response_time, p95_response_time, p99_response_time number
Latency percentiles (ms).
status_code_breakdown object
Counts by status class:
{success, redirect, client_err, server_err, other, total, success_rate} (2xx / 3xx / 4xx / 5xx).total_bandwidth, total_bandwidth_in, total_bandwidth_out int64
Bandwidth aggregates in bytes.
unique_visitors int
Distinct source IPs in the window.
peak_requests_per_hour int64
Busiest hour's request count.
time_series_requests, time_series_response_times, time_series_bandwidth, time_series_errors array
Bucketed series. Each point carries
timestamp, label, and value field(s) (e.g. value, or bytes_in/bytes_out, or value_4xx/value_5xx).top_endpoints_by_requests, _by_response_time, _by_errors, _by_bandwidth array
Top 5 endpoints per metric. Each item:
{endpoint_id, endpoint_uuid, endpoint_name, public_url, count, value, …}.method_distribution, top_countries, status_code_detail, error_type_breakdown array
Method mix, geo distribution, per-code counts, and error-cause attribution.
slo_data object
Availability/latency/error-budget SLOs for the window.
start_time, end_time, time_range datetime / string
Resolved window bounds plus the duration string.
*_change number
Percentage change vs the immediately-preceding window of the same length (e.g.
total_requests_change, error_rate_change, total_bandwidth_change).Errors
400 Bad Request
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?time_range=24h" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
m = client.traffic.get_metrics()
print(f"{m['total_requests']} req, {m['error_rate']:.2f}% errors, p99 {m['p99_response_time']}ms")
Response — 200 OK
{
"total_requests": 152340,
"error_rate": 0.15,
"average_response_time": 22.4,
"median_response_time": 15,
"p95_response_time": 89,
"p99_response_time": 245,
"status_code_breakdown": {
"success": 149800, "redirect": 1200, "client_err": 1106,
"server_err": 234, "other": 0, "total": 152340, "success_rate": 98.33
},
"total_bandwidth": 100000000,
"total_bandwidth_in": 12345678,
"total_bandwidth_out": 87654321,
"unique_visitors": 4821,
"peak_requests_per_hour": 9870,
"top_endpoints_by_requests": [
{"endpoint_id": 12, "endpoint_uuid": "abc-...", "endpoint_name": "myapp",
"public_url": "myapp.example.com", "count": 12340, "value": 12340.0,
"bandwidth": 8888888, "p95": 47.0}
],
"method_distribution": [{"method": "GET", "count": 140000, "percentage": 91.9}],
"start_time": "2026-04-29T00:00:00Z",
"end_time": "2026-04-30T00:00:00Z",
"time_range": "24h0m0s",
"total_requests_change": 12.4,
"error_rate_change": -3.1
}