# Cardinality Explorer API Reference

The Cardinality Explorer API provides programmatic access to the cardinality data surfaced by the [Metrics Cardinality Explorer](https://docs.kloudfuse.com/platform/4.1.0/signals/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.<br>Use a metric name with or without label filters (e.g. `kube_pod_info{namespace="kube-system"}`) to scope to a specific metric.<br>Use a bare label selector (e.g. `{namespace="kube-system"}`) to scope across all metrics matching those labels.<br>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"}`.<br>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.

```bash
# 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

```json
[
  {
    "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

| 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.

```bash
# 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

| 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

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

### 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.

```bash
# 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

| 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

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

### 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. |

## 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. |