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_uuid string (uuid)
Optional. Restrict to a single endpoint by its
uuid. A uuid outside your account is ignored.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)
A flat object. Every key below is always present; lists are [] when the window has no traffic.
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; other is always 0; success_rate is the 2xx share in percent).status_code_detail object[]
Count per exact status code:
{status_code, count}.error_type_breakdown object[]
Why requests failed:
{key, label, count, percent} per cause, with key one of firewall_block, rate_limited, origin_offline, bad_gateway (502/504), server_error (500), auth_failure (401/403), not_found (404), client_error (other 4xx). percent is the share of all failed requests.total_bandwidth, total_bandwidth_in, total_bandwidth_out int64
Bandwidth aggregates in bytes (
total_bandwidth = in + out).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 object[]
Bucketed series of request counts and of mean latency (ms). Each point:
{timestamp, label, value}; label is the bucket formatted for display.time_series_bandwidth object[]
Bucketed bandwidth:
{timestamp, label, bytes_in, bytes_out}.time_series_errors object[]
Bucketed error counts:
{timestamp, label, value_4xx, value_5xx}.per_endpoint_series object
Request counts per endpoint on the same buckets as
time_series_requests, keyed by endpoint uuid: {"<endpoint uuid>": {"labels": [...], "values": [...]}}. An endpoint with no traffic in the window has no key.top_endpoints_by_requests, top_endpoints_by_response_time, top_endpoints_by_errors, top_endpoints_by_bandwidth object[]
Up to 5 endpoints per metric, highest first. Each item:
endpoint_uuid, endpoint_name (subdomain), public_url, count (requests; error responses for _by_errors) and value (the ranked metric: requests, mean latency in ms, error responses, or bytes). top_endpoints_by_requests items also carry bandwidth (bytes) and p95: the endpoint's 95th-percentile latency in ms over the window, computed like p95_response_time (0 when none of its requests recorded a latency).method_distribution object[]
Request mix by HTTP method:
{method, count, percentage}.top_countries object[]
Up to 10 client countries:
{code, count, percentage} (code is the ISO country code).slo_data object
SLOs for the window, against your SLO targets:
availability and availability_target (percent), latency_threshold_ms and latency_target_percent, the error budget (error_budget_total, error_budget_consumed in requests, error_budget_remaining_percent), burn_rate, two chart series burn_down_chart and latency_sli_chart (points {timestamp, value, label}), and slis: {name, definition, objective, status, compliance} per SLI, status being Met, At Risk or Violated.start_time, end_time, time_range datetime / string
Resolved window bounds plus its length as a Go duration string (e.g.
24h0m0s).*_change number
Percentage change vs the immediately-preceding window of the same length:
total_requests_change, average_response_time_change, error_rate_change, error_rate_4xx_change, error_rate_5xx_change, total_errors_change, total_bandwidth_change, total_bandwidth_in_change, total_bandwidth_out_change. 100 when the previous window was zero and this one isn't.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 value, or endpoint_id and endpoint_uuid naming different endpoints (id_uuid_mismatch).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,
"status_code_detail": [{"status_code": 200, "count": 149800}, {"status_code": 404, "count": 1106}],
"error_type_breakdown": [
{"key": "not_found", "label": "Not found (404)", "count": 1106, "percent": 82.5},
{"key": "server_error", "label": "Server error (500)", "count": 234, "percent": 17.5}
],
"time_series_requests": [{"timestamp": "2026-04-29T13:00:00Z", "label": "Apr 29 13:00", "value": 6420}],
"per_endpoint_series": {
"019bb1e4-e785-77d2-9966-c3cff31d0a0e": {"labels": ["Apr 29 13:00"], "values": [514]}
},
"top_endpoints_by_requests": [
{"endpoint_uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "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}],
"top_countries": [{"code": "DE", "count": 52000, "percentage": 34.1}],
"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
}
Was this helpful?