List Logs - Ngris

List Traffic Logs

GET /v1/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 (typically 7 days; the extra-retention-90d add-on pushes this to 90).

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, max 200.

endpoint_id string

Filter to a single endpoint. Accepts the endpoint UUID or its numeric id.

since, until string (RFC 3339)

Time window (UTC). Defaults to last hour if both omitted.

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.

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_id string

Filter to requests that matched a specific traffic policy.

firewall_action string

Filter by the firewall verdict recorded on the request (e.g. allow, block).

rate_action string

Filter by the rate-limit action recorded on the request.

rate_limit_rule_id int

Filter to requests that matched a specific rate-limit rule.

since_id int

Return only rows with an id greater than this. Cursor-style polling for new 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. 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 string

Operator for the enumerable dimensions. One of equals, not_equals, in, not_in.

Response (200 OK)

items array

Log entries (compact). Each:

{id, method, path, host, tunnel_type, public_url, connection_id, source_ip, status_code, origin_status, latency_ms, duration_ms, edge_ms, origin_ttfb_ms, transfer_ms, bytes_in, bytes_out, firewall_action, rate_limit_action, is_replay, geo_info, created_at}

. The IP is source_ip and the HTTP status is status_code (there is no timestamp or endpoint_uuid field). Use GET /v1/traffic/logs/{id} for the full record (headers, body samples, hit policies).

total, page, page_size int

Pagination metadata. total is the unfiltered match count.

Errors

400 Bad Request

Time-window pagination offset too large, or invalid filter value.

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" \
  -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
{
  "items": [
    {
      "id": 1234,
      "method": "GET",
      "path": "/api/users",
      "host": "myapp.ngris.io",
      "tunnel_type": "http",
      "public_url": "myapp.ngris.io",
      "source_ip": "203.0.113.42",
      "status_code": 500,
      "origin_status": 500,
      "latency_ms": 1247,
      "duration_ms": 1247,
      "bytes_in": 0,
      "bytes_out": 234,
      "is_replay": false,
      "created_at": "2026-04-29T13:01:23.456Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50
}

PreviousTraffic Policy Rule Types NextGet Log Entry

On this page

List Traffic Logs