List Traffic Logs
Query the traffic-log inspector — every request handled by your endpoints (inbound and outbound) is recorded here. Filterable by endpoint, time range, status code, path, method, and more. The retention window depends on your plan, plus any extra-retention add-on; every response carries your account's window as retention_days.
Returns paginated results ordered by created_at DESC. For ad-hoc human-readable queries, use /traffic/smart-search which accepts natural-language input.
Plan-gated: requires the traffic_inspector entitlement. Callers without it receive 403 Forbidden.
Query parameters
page int
1-indexed page. Default
1.page_size int
Items per page. Default
50; values above 200 are capped at 200.endpoint_uuid string (uuid)
Filter to a single endpoint (its
uuid).request_id string
The
X-Request-Id response header the edge returned for a request. Returns that request's entry (exact match, only within your active account; a request id from another account matches nothing). Entries are written asynchronously, so a request made a moment ago can take a few seconds to show up.since, until string (RFC 3339)
Time window (UTC), matched on the time the edge received the request. There is no default window: without
since, until and time_range every entry still within retention matches.time_range string
Convenience relative window applied only when
since is absent. One of 1h, 24h, 7d (also 6h).status string
Status filter. Single code (
500), class (5xx), or comma-separated (404,500).method string
HTTP verb (case-insensitive).
protocol string
Transport-level scheme as derived from the recorded request URL. One of
http, tcp, udp, or a comma-separated combination (tcp,udp). Useful for noisy mixed-traffic accounts where you want to look at one transport in isolation — the same dropdown powers the traffic inspector.region string
The edge region that served the request (e.g.
eu-fi), or a comma-separated list. Pair with region_op (equals | not_equals | in | not_in) to exclude regions instead. Entries recorded before regions were logged have no region and never match.path string
Path glob/substring (URL-encoded).
client_ip string
IP address or CIDR. Legacy free-text filter; prefer the
source_ip condition-builder dimension below.search string
Free-text substring match across the searchable log columns.
policy_uuid string (uuid)
Filter to requests that matched a specific firewall policy (its
uuid).firewall_action string
Filter by the firewall verdict recorded on the request (e.g.
allowed, blocked, no_match; see firewall_action below).rate_action string
Filter by the rate-limit action recorded on the request (
allowed, throttled or blocked).rate_limit_rule_uuid string (uuid)
Filter to requests that matched a specific rate-limit rule (its
uuid).since_uuid string (uuid)
Return only entries newer than the log entry with this
uuid. Cursor-style polling for new entries.Deprecated: endpoint_id, rate_limit_rule_id and since_id (integers) and policy_id are still accepted until the sunset. Send endpoint_uuid, rate_limit_rule_uuid, since_uuid and policy_uuid; sending both forms for different objects is a 400 id_uuid_mismatch. A uuid that names nothing in your active account matches no entries.
Advanced filters (condition builder)
Each filterable dimension can be combined with an optional <dim>_op operator, mirroring the Traffic Inspector's condition builder. The dimensions are host, path, method, source_ip, status, protocol, asn, country, ua, browser, os, region (the serving edge region) and http_version (HTTP/1.1, HTTP/2, HTTP/3). Values are comma-separated; when <dim>_op is omitted the operator defaults to equals for a single value or in for multiple values.
host_op, path_op, ua_op string
Operator for the free-text dimensions. One of
equals, not_equals, contains, starts_with, ends_with, in, not_in.method_op, source_ip_op, status_op, protocol_op, asn_op, country_op, browser_op, os_op, region_op, http_version_op string
Operator for the enumerable dimensions. One of
equals, not_equals, in, not_in.Response (200 OK)
items object[]
Log entries for this page, newest first (compact form; fields below). Always present; an empty page is
[]. Use GET /v1/traffic/logs/{uuid} for the full record (headers, cookies, body samples, bot score).total int
Number of entries matching the filters, across all pages.
page int
The page that was returned.
page_size int
The effective page size (after the cap).
retention_days int
How many days traffic logs are kept for your account: your plan's retention plus any extra-retention add-on. The same on every page.
Log entry (items[])
Most fields are optional: a field is omitted (not null) when the entry has no value for it. The IP is source_ip and the HTTP status is status_code; the list has no timestamp or endpoint_uuid field.
uuid string (uuid)
request_id string?
The edge's
X-Request-Id for the request. Omitted on TCP/UDP sessions, entries from before request ids were recorded, and some edge-generated error responses.method, path, host string?
The HTTP request line and
Host. Omitted on TCP/UDP session entries.tunnel_type string?
Type of the tunnel that carried the request (e.g.
http, tcp, udp). Omitted when the entry has no tunnel (agentless or managed hosting, or a deleted tunnel).public_url string?
That tunnel's public address: the bare hostname for HTTP,
tcp://host:port / udp://host:port for raw TCP/UDP. Omitted when the entry has no tunnel.region string?
The edge region that served the request (see regions). Omitted on entries recorded before regions were logged.
http_version string?
Negotiated HTTP version:
HTTP/1.1, HTTP/2 or HTTP/3. Omitted on TCP/UDP sessions and older entries.connection_id string?
Session id of a TCP/UDP session entry. Omitted for HTTP requests.
source_ip string
The client's IP address (
Unknown when it wasn't recorded).status_code int?
Status the client got from the edge. Omitted on TCP/UDP sessions.
origin_status int?
Status your origin returned. Omitted when the origin wasn't reached (blocked or answered at the edge) or wasn't recorded.
duration_ms int?
Full request time in ms, from when the edge received the request to when the client had the whole response. Equals
edge_ms + origin_ttfb_ms + transfer_ms when those are present.edge_ms, origin_ttfb_ms, transfer_ms int?
The three timing phases in ms: edge processing before your origin is contacted, wait for the origin's first byte, and response-body transfer. Each is omitted when the phase wasn't measured (older entries, requests answered at the edge, TCP/UDP sessions).
latency_ms int?
Time to the origin's first byte in ms (the same value as
origin_ttfb_ms). Omitted when the origin wasn't reached.bytes_in, bytes_out int64
Bytes received from the client and sent back. Always present (
0 when none); for a TCP/UDP session they are the session totals.firewall_action string?
What the edge did with the request:
no_match (no firewall policy matched), allowed or blocked by a firewall policy, or the traffic-policy outcome when one answered at the edge (e.g. redirect, cache_hit, edge_function). Omitted when not recorded.rate_limit_action string?
The rate-limit verdict:
allowed, throttled or blocked. Omitted when no rate limit was evaluated.is_replay boolean
true when the entry is a replay of an earlier request.geo_info object?
Where the client IP is: string values
country (ISO code) and, when known, asn (e.g. AS64496), asn_org, continent, timezone, latitude, longitude. Omitted when the IP wasn't resolved.spam_score int?
Reputation score of the client IP, 0–100 (higher is worse). Omitted when the reputation check didn't run.
ip_health string?
Reputation verdict for the client IP:
clean, suspect, malicious, blocked or allowlisted. Omitted when the reputation check didn't run.created_at datetime
When the entry was recorded (RFC 3339, UTC).
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
Time-window pagination offset too large, an invalid filter value, a malformed
*_uuid filter ("endpoint_uuid must be a uuid"), id_uuid_mismatch, or an integer id after the sunset (integer_id_unsupported).401 Unauthorized
Missing auth.
403 Forbidden
Plan doesn't include the
traffic_inspector entitlement.Request — 5xx in last 15 min
curl "https://api.ngris.com/v1/traffic/logs?status=5xx&since=2026-04-29T13:00:00Z&endpoint_uuid=019bb1e4-e785-77d2-9966-c3cff31d0a0e" \
-H "X-API-KEY: <your_api_key>"
Request — find one request by its X-Request-Id
curl -sI "https://myapp.ngris.io/api/users" | grep -i x-request-id
# x-request-id: 4f9c2b7e1d0a8c3b6e5f7a9d2c1b0e8f
curl "https://api.ngris.com/v1/traffic/logs?request_id=4f9c2b7e1d0a8c3b6e5f7a9d2c1b0e8f" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
page = client.traffic.list_logs(page=1, page_size=100)
for log in page.items:
print(f"{log.created_at} {log.method} {log.path} -> {log.status_code}")
Response — 200 OK (abridged)
{
"items": [
{
"uuid": "019ba303-954b-796c-bf40-f33a26697f74",
"request_id": "4f9c2b7e1d0a8c3b6e5f7a9d2c1b0e8f",
"method": "GET",
"path": "/api/users",
"host": "myapp.ngris.io",
"tunnel_type": "http",
"public_url": "myapp.ngris.io",
"region": "eu-fi",
"http_version": "HTTP/2",
"source_ip": "203.0.113.42",
"status_code": 500,
"origin_status": 500,
"latency_ms": 1243,
"duration_ms": 1247,
"edge_ms": 2,
"origin_ttfb_ms": 1243,
"transfer_ms": 2,
"bytes_in": 0,
"bytes_out": 234,
"firewall_action": "no_match",
"rate_limit_action": "allowed",
"is_replay": false,
"geo_info": {"country": "DE", "asn": "AS64496", "asn_org": "Example Hosting"},
"spam_score": 0,
"ip_health": "clean",
"created_at": "2026-04-29T13:01:23.456Z"
}
],
"total": 12,
"page": 1,
"page_size": 50
}
Was this helpful?