Smart Search Logs

Smart Search

POST /v1/traffic/smart-search

Natural-language traffic-log search. The platform's AI gateway translates a free-form query ("5xx errors from mobile clients in the last hour") into a structured traffic-log filter, runs it, and returns the matching logs. The response is the same shape as GET /v1/traffic/logs — the AI only chooses the filter; the result set is the ordinary, paginated log list.

Plan-gated: requires the traffic_inspector entitlement and the traffic-inspector read permission. Strict JSON decoding — only query is allowed in the body; any unknown field is rejected.

If the AI can't translate your wording into an actionable filter, the call returns 400 ("Smart search could not understand the request"). Refine your wording or use the structured /traffic/logs endpoint instead.

Request body

query string Req

Free-form natural-language question. Must be non-empty.

Response (200 OK)

Identical to GET /v1/traffic/logs: the AI-derived filter is applied server-side and the matching page of logs is returned.

items, logs array

Matching log entries (compact form). logs is an alias of items kept for backward compatibility — they are the same list.

total, page, page_size int

Pagination metadata for the filtered result set.

pagination object

{page, page_size, total} — the same numbers nested for clients that read the object form.

retention_days int

Effective traffic-log retention window for the caller (plan retention plus any extra-retention add-on).

Errors

400 Bad Request

Empty query, unknown body fields (strict decoding), or the AI couldn't translate the query into actionable filters.

401 Unauthorized

Missing auth.

403 Forbidden

The active account's plan lacks the traffic_inspector entitlement, or the member lacks traffic-inspector read permission.

500

AI gateway error while resolving the query. Try again or switch to structured search.

501 Not Implemented

Smart search isn't enabled on this deployment (no AI gateway configured).

Request
curl -X POST "https://api.ngris.com/v1/traffic/smart-search" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "5xx errors in the last hour"}'

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
result = client.traffic.smart_search("5xx errors in the last hour")
for log in result["items"]:
    print(f"  {log['created_at']} {log['method']} {log['path']} {log['status_code']}")

Response — 200 OK
{
  "items": [
    {
      "id": 1234,
      "created_at": "2026-04-29T13:01:23Z",
      "method": "GET",
      "path": "/api/users",
      "host": "api.example.com",
      "source_ip": "203.0.113.7",
      "status_code": 500,
      "duration_ms": 1247
    }
  ],
  "logs": [
    {
      "id": 1234,
      "created_at": "2026-04-29T13:01:23Z",
      "method": "GET",
      "path": "/api/users",
      "host": "api.example.com",
      "source_ip": "203.0.113.7",
      "status_code": 500,
      "duration_ms": 1247
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50,
  "retention_days": 7,
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 12
  }
}

PreviousGet Log Entry NextAI Analysis

On this page

Smart Search