Cardinality Explorer API Reference

The Cardinality Explorer API provides programmatic access to the cardinality data surfaced by the Metrics Cardinality Explorer UI. Use it to retrieve metric series counts, label series counts, and label value counts, with optional filters to scope results to a specific metric or label-value combination.

All three endpoints are under the /api/v1/cardinality/ base path and use a Service Account Bearer token for authentication.

Replace <your-instance> with your Kloudfuse hostname and <sa-token> with a valid Service Account token.

Common Parameters

All three endpoints share the same time range parameters.

Parameter Type Description

timestamp

integer

End of the time range as a Unix timestamp (seconds). Required.

duration

integer

Length of the time range in seconds. Use 0 for an instant query at timestamp. Required.

rollUpSeconds

integer

Aggregation bucket size in seconds. Set to the same value as duration for a single-bucket result. Required.

match[]

string

Optional PromQL selector to filter results. Accepts standard Prometheus selector syntax. Use a metric name with or without label filters (e.g. kube_pod_info\{namespace="kube-system"\}) to scope to a specific metric. Use a bare label selector (e.g. \{namespace="kube-system"\}) to scope across all metrics matching those labels. To filter on multiple values for a label — equivalent to selecting several values in the UI before promoting — use a regex matcher with | as the OR separator: \{host=~"node-1|node-2"\}. Can be repeated for multiple independent matchers.
The Cardinality Explorer UI enforces a maximum time range of 5 minutes. The API does not impose this limit, but wider ranges increase response time significantly.

Get Metric Series Counts

Returns all metric names and their series counts within the given time range and filter scope.

# All metrics, instant query
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     "https://<your-instance>/api/v1/cardinality/metrics_series"

# Scoped to a single label-value
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "match[]={namespace=\"kube-system\"}" \
     "https://<your-instance>/api/v1/cardinality/metrics_series"

# Scoped to multiple selected values for a label (regex OR)
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "match[]={host=~\"node-1|node-2\"}" \
     "https://<your-instance>/api/v1/cardinality/metrics_series"
bash
Response
[
  {
    "bucketStart": 1745279700,
    "overallCardinality": 26206,
    "metricNames": {
      "kube_pod_info": 312,
      "kube_node_status_capacity": 18,
      "container_cpu_usage_seconds_total": 934
    }
  }
]
json

The response is an array of time buckets. For instant queries (duration=0) the array contains a single element.

Response fields

Field Type Description

bucketStart

integer

Start of the bucket as a Unix timestamp (seconds).

overallCardinality

integer

Total number of unique time series across all metrics in scope.

metricNames

object

Map of metric name → series count. Each entry is the number of unique time series for that metric within the time range and filter scope.

Get Label Series Counts

Returns all label names and the number of unique time series that include each label, optionally scoped to a metric or label-value filter. This is the data behind the series count toggle in the Labels column of the Cardinality Explorer UI.

# All labels across all metrics
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "aggregation=distinctcount" \
     "https://<your-instance>/api/v1/cardinality/series"

# Labels scoped to a specific metric
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "aggregation=distinctcount" \
     --data-urlencode "match[]=kube_pod_info{}" \
     "https://<your-instance>/api/v1/cardinality/series"

# Labels for a metric, scoped to multiple selected values for another label (regex OR)
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "aggregation=distinctcount" \
     --data-urlencode "match[]=kube_pod_info{host=~\"node-1|node-2\"}" \
     "https://<your-instance>/api/v1/cardinality/series"
bash

Additional parameters

Parameter Type Description

aggregation

string

Must be distinctcount. Required.

label

string (repeatable)

Optional. When provided, restricts results to the specified label names. Repeat the parameter to request multiple labels.
Response
[
  {
    "bucketStart": 1745279700,
    "overallCardinality": 26206,
    "labelNames": {
      "namespace": 24,
      "pod": 312,
      "container": 87,
      "node": 18
    }
  }
]
json

Response fields

Field Type Description

bucketStart

integer

Start of the bucket as a Unix timestamp (seconds).

overallCardinality

integer

Total number of unique time series in scope.

labelNames

object

Map of label name → series count. Each entry is the number of unique time series that carry this label within the time range and filter scope.

Get Label Value Counts

Returns the number of distinct values for each requested label name, optionally scoped to a metric. This is the value count displayed in the Labels column of the Cardinality Explorer UI.

# Value count for specific labels
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "aggregation=distinctcount" \
     --data-urlencode "label=namespace" \
     --data-urlencode "label=pod" \
     "https://<your-instance>/api/v1/cardinality/label_values"

# Value count scoped to a specific metric
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "aggregation=distinctcount" \
     --data-urlencode "label=namespace" \
     --data-urlencode "match[]=kube_pod_info{}" \
     "https://<your-instance>/api/v1/cardinality/label_values"

# Value count with multiple selected values promoted as a filter (regex OR)
curl -H "Authorization: Bearer <sa-token>" \
     -G \
     --data-urlencode "timestamp=1745280000" \
     --data-urlencode "duration=0" \
     --data-urlencode "rollUpSeconds=300" \
     --data-urlencode "aggregation=distinctcount" \
     --data-urlencode "label=namespace" \
     --data-urlencode "match[]={host=~\"node-1|node-2\"}" \
     "https://<your-instance>/api/v1/cardinality/label_values"
bash

Additional parameters

Parameter Type Description

aggregation

string

Must be distinctcount. Required.

label

string (repeatable)

One or more label names to return value counts for. Repeat the parameter for each label.
Response
[
  {
    "bucketStart": 1745279700,
    "labelNames": {
      "namespace": 24,
      "pod": 312
    }
  }
]
json

Response fields

Field Type Description

bucketStart

integer

Start of the bucket as a Unix timestamp (seconds).

labelNames

object

Map of label name → distinct value count. Each entry is the number of unique values observed for that label within the time range and filter scope.
Unlike the series endpoint, this endpoint counts distinct values per label — not the number of time series. A label with 5 values but 1000 series would return 5 here.

Error Codes

HTTP Status Meaning

200

Success.

400

Bad request — missing required parameter or invalid selector syntax.

401

Missing or invalid Authorization header.

403

Insufficient permissions.

See Also