Logs & Traces API

KubeSense exposes the same logs and traces data you see in the UI through a REST API. This lets in-house tools, scripts, and integrations pull logs and traces programmatically — authenticating with an API key instead of an interactive login.

This guide covers authentication, request conventions, and the /logs and /traces endpoints. For querying metrics, see the Metrics API.

Base URL

All endpoints are served under the /api prefix on your KubeSense host:

https://<your-kubesense-host>/api

So the logs endpoint is https://<your-kubesense-host>/api/logs and traces is https://<your-kubesense-host>/api/traces.

Authentication

External tools authenticate with an API key passed in the X-API-Key header. Every request to a logs or traces endpoint must include it:

X-API-Key: <your-api-key>

Creating an API key

1. In the KubeSense UI, go to Settings → API Key Management.
2. Generate a new key and give it a descriptive label (e.g. inhouse-log-exporter).
3. Copy the key immediately — it is shown only once at creation time. Store it as a secret in your tool.

Verifying access

A quick way to confirm the key works:

curl -s "https://<your-kubesense-host>/api/logs" \
  -H "X-API-Key: $KUBESENSE_API_KEY"

A 401 Unauthorized with "message": "invalid api key" means the key is wrong or expired. A 200 with a hierarchy payload means you're in.

Request conventions

Both APIs follow the same patterns.

Response envelope

Responses are wrapped in a consistent envelope:

{
  "data": { },
  "error": false,
  "message": "fetched logs successfully"
}

On failure, error is true and message describes the problem. Auth failures return HTTP 401; malformed requests return 400; query timeouts return 500 with a warning message.

Logs API

Fetch logs

POST /api/logs — time range and pagination go in the query string; filters and field selection go in the JSON body.

curl -s -X POST \
  "https://<your-kubesense-host>/api/logs?from_time=2026-05-27T00:00:00Z&to_time=2026-05-27T01:00:00Z&cluster=mpokket-neo-prod-eks-cluster" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "type": "common",
      "common_filter": [
        { "field": "namespace", "operation": "IN", "values": ["payments"], "type": "string" }
      ]
    },
    "sort_by": "timestamp",
    "sort_order": "desc",
    "page": 1,
    "page_size": 50
  }'

To pull all logs in the window, send an empty filter set:

{ "filters": { "common_filter": [] }, "page_size": 100 }

The response data contains the matched log rows plus total_logs_count and error_count. Page through results by incrementing page.

Request body fields

Traces API

Fetch traces

POST /api/traces — same shape as logs: time range and pagination in the query string, filters in the body.

curl -s -X POST \
  "https://<your-kubesense-host>/api/traces?from_time=2026-05-27T00:00:00Z&to_time=2026-05-27T01:00:00Z&cluster=mpokket-neo-prod-eks-cluster&page=1&page_size=50" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "type": "common",
      "common_filter": [
        { "field": "workload", "operation": "IN", "values": ["checkout-service"], "type": "string" }
      ]
    },
    "operator": "AND",
    "sort_by": "timestamp",
    "sort_direction": "desc",
    "page": 1,
    "page_size": 50
  }'

Filtering

Both APIs use the same filter object. The common case is a flat list of conditions in common_filter:

{
  "filters": {
    "type": "common",
    "common_filter": [
      { "field": "namespace", "operation": "IN",  "values": ["payments"], "type": "string" },
      { "field": "level",     "operation": "IN",  "values": ["error"],    "type": "string" }
    ]
  }
}

Each condition has:

Common operations:

Multiple conditions combine with the operator (AND / OR). For nested boolean logic, use the adv_filters object instead of common_filter. The easiest way to discover valid field names and values is to call POST /api/logs/filters (or /api/traces/filter), which returns the same facets the Explorer UI shows.

Advanced querying (SPL)

For analytics-style queries — aggregations, field extraction, time-series — KubeSense supports Search Processing Language (SPL), a pipeline query language over the same logs data. SPL queries are a series of commands joined by |, where each command's output feeds the next.

Request body fields

Run a query

curl -s -X POST \
  "https://<your-kubesense-host>/api/logs/spl/execute" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fields @timestamp, workload, level, body | filter level = \"ERROR\" | sort @timestamp desc | limit 50",
    "clusters": ["mpokket-neo-prod-eks-cluster"],
    "from_time": "2026-05-27T00:00:00Z",
    "to_time": "2026-05-27T01:00:00Z"
  }'

The result is column-oriented — a list of column names plus an array of row arrays:

{
  "error": false,
  "message": "query executed successfully",
  "data": {
    "columns": ["@timestamp", "workload", "level", "body"],
    "rows": [
      ["2026-05-27T00:59:12.4Z", "checkout-service", "ERROR", "payment gateway timeout"]
    ],
    "count": 1
  }
}

Example queries

Filter for errors in a namespace, newest first:

fields @timestamp, body, level
| filter namespace = "payments" and level = "ERROR"
| sort @timestamp desc
| limit 50

Error rate per workload (aggregation):

fields workload as application_name, level as severity
| filter severity in ["ERROR", "WARN", "INFO"]
| stats count(*) as total, sum(severity = "ERROR") as errors by application_name
| eval error_rate = errors / total
| sort error_rate desc

Top 10 noisiest namespaces:

filter level = "ERROR"
| top 10 namespace

Bare keyword search (case-insensitive substring match on the log body):

"timeout" and "payment"

Access parsed fields from structured logs with the log_processed. prefix:

filter log_processed.status = "500"
| stats count(*) as total by log_processed.url

See the SPL Reference for the full command and function list, and Query Jobs for running long SPL queries as asynchronous, exportable jobs.

Errors