Metrics API

KubeSense stores metrics as Prometheus-style time series and exposes them through the Metrics Exploration endpoints under /api/explore. Use them to discover available metrics and to run PromQL queries for charts, dashboards, or current values — authenticating with an API key instead of an interactive login.

These endpoints share the same authentication as the Logs & Traces API.

Base URL

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

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

Authentication

Every request must include your API key in the X-API-Key header, plus the standard JSON headers:

X-API-Key: <your-api-key>
accept: */*
content-type: application/json

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-metrics-exporter).
3. Copy the key immediately — it is shown only once at creation time. Store it as a secret in your tool.

List metrics

POST /api/explore/metrics returns the metric names available in the database for a time range. The name field does a substring match on metric names — e.g. "jvm" matches jvm.class.count, jvm.memory.used, and jvm.gc.pause.

curl -s -X POST \
  "https://<your-kubesense-host>/api/explore/metrics" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "accept: */*" \
  -H "content-type: application/json" \
  -d '{
    "filters": [],
    "from_time": "2026-02-12T13:16:00.000Z",
    "to_time": "2026-02-12T13:31:00.000Z",
    "limit": 50,
    "name": "jvm"
  }'

Request body fields

The response is the list of matching metric names plus a total count:

{
  "metrics": [
    "jvm.class.count",
    "jvm.memory.used",
    "jvm.gc.pause"
  ],
  "total": 3
}

Query a time range

POST /api/explore/query-range evaluates a PromQL query at regular intervals across a time range — the shape you want for charts and dashboards. Queries are keyed (A, B, …) inside a queries object so you can evaluate several at once.

curl -s -X POST \
  "https://<your-kubesense-host>/api/explore/query-range" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "accept: */*" \
  -H "content-type: application/json" \
  -d '{
    "filters": [],
    "queries": {
      "A": {
        "from_time": "2026-02-12T13:16:00.000Z",
        "to_time": "2026-02-12T13:31:00.000Z",
        "promql": "jvm.class.count{}",
        "step": 30,
        "page": 1,
        "page_size": 50
      }
    }
  }'

Request body fields

Each entry in queries accepts:

The step parameter

step defines the interval between data points returned across the range:

Smaller steps return more points; use larger steps over wide ranges to keep responses fast.

Response

The response follows the Prometheus result format — one entry per series, each with its labels and an array of [timestamp, value] points:

{
  "status": "success",
  "data": {
    "result": [
      {
        "metric": { "__name__": "jvm.class.count" },
        "values": [
          [1707743760, "123"],
          [1707743790, "124"],
          [1707743820, "125"]
        ]
      }
    ]
  }
}

Query an instant value

POST /api/explore/query takes the same request body as /query-range but returns the most recent value of the query within the time range — useful for single-stat tiles and current-value lookups.

curl -s -X POST \
  "https://<your-kubesense-host>/api/explore/query" \
  -H "X-API-Key: $KUBESENSE_API_KEY" \
  -H "accept: */*" \
  -H "content-type: application/json" \
  -d '{
    "filters": [],
    "queries": {
      "A": {
        "from_time": "2026-02-12T13:19:46.000Z",
        "to_time": "2026-02-12T13:34:46.000Z",
        "promql": "sum(jvm.class.count{})",
        "step": 30,
        "page": 1,
        "page_size": 50
      }
    }
  }'

Each series returns a single [timestamp, value] pair:

{
  "status": "success",
  "data": {
    "result": [
      {
        "metric": {},
        "value": [1707744086, "245"]
      }
    ]
  }
}

PromQL examples

Replace the promql field with any valid Prometheus expression.

Errors

On failure, the response sets status to error and includes a message:

{
  "status": "error",
  "message": "Invalid API key"
}

Best practices

• Call /api/explore/metrics first to discover the exact metric names available.
• Use /query-range for charts and dashboards (data over time).
• Use /query for current/latest values (single-stat tiles).
• Choose an appropriate step for the range to keep responses fast and readable.