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.

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"

Response

[
  {
    "bucketStart": 1745279700,
    "overallCardinality": 26206,
    "metricNames": {
      "kube_pod_info": 312,
      "kube_node_status_capacity": 18,
      "container_cpu_usage_seconds_total": 934
    }
  }
]

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

Response fields

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"

Additional parameters

Response

[
  {
    "bucketStart": 1745279700,
    "overallCardinality": 26206,
    "labelNames": {
      "namespace": 24,
      "pod": 312,
      "container": 87,
      "node": 18
    }
  }
]

Response fields

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"

Additional parameters

Response

[
  {
    "bucketStart": 1745279700,
    "labelNames": {
      "namespace": 24,
      "pod": 312
    }
  }
]

Response fields

Error Codes