---
title: "Native histograms cardinality API | Grafana Cloud documentation"
description: "Analyze the cardinality of native histograms With the native histograms data type, the resolution of your metrics is automatically generated based on the number of buckets used to represent your data distribution. Native histograms typically provide a higher-resolution data representation compared to classic histograms, for which you predefine the number of buckets to provision."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Analyze the cardinality of native histograms

With the native histograms data type, the resolution of your metrics is automatically generated based on the number of buckets used to represent your data distribution. Native histograms typically provide a higher-resolution data representation compared to classic histograms, for which you predefine the number of buckets to provision.

Use the cardinality API to retrieve statistics on the buckets used in a native histogram. You can then determine which metrics use more buckets than expected and limit those buckets to reduce costs.

> Note
> 
> The native histograms cardinality API is currently [experimental](/docs/release-life-cycle/). Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.

## Prerequisites

Before you can use the cardinality API, you need to complete the following prerequisites.

- Install [curl](https://curl.se/) on your machine.
- Set your environment variables. Refer to [Set the environment to query the API](/docs/grafana-cloud/cost-management-and-billing/analyze-costs/metrics-costs/prometheus-metrics-costs/usage-analysis-api/#set-the-environment-to-query-the-api) for details.
- Ensure that your Grafana Cloud access policy includes the `metrics:read` scope. Refer to [Grafana Cloud access policies](/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/).

## Fetch statistics for native histograms buckets

You can fetch statistics on the cardinality of active native histograms series, including the number of buckets in use. A series is considered active if it has sent data points to Grafana Cloud in the last twenty minutes. Refer to [Active series](/docs/grafana-cloud/cost-management-and-billing/understand-your-invoice/metrics-invoice/#active-series) for details.

Use curl to send a GET HTTP request to the `/cardinality/active_native_histogram_metrics` endpoint. Include the metric name as a parameter.

Set `PROMETHEUS_HTTP_PREFIX` to the Mimir Prometheus HTTP prefix for your metrics instance. Since this is a [Mimir-only endpoint](/docs/grafana-cloud/send-data/metrics/metrics-prometheus/query-http-api/#use-the-mimir-prometheus-http-prefix-for-mimir-only-endpoints), the `PROMETHEUS_HTTP_PREFIX` might look something like `https://prometheus-prod-56-prod-us-east-2.grafana.net/prometheus`, not `https://prometheus-prod-56-prod-us-east-2.grafana.net/api/prom`.

Example request:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
PROMETHEUS_HTTP_PREFIX="<PROMETHEUS_HTTP_PREFIX>"

curl -G -u $login "$PROMETHEUS_HTTP_PREFIX/api/v1/cardinality/active_native_histogram_metrics" \
--data-urlencode 'selector={__name__=~".+"}'
```

Example response:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "data": [
    {
      "metric": "cluster_job:cortex_request_duration_seconds:sum_rate",
      "series_count": 24,
      "bucket_count": 509,
      "avg_bucket_count": 21.208333333333332,
      "min_bucket_count": 7,
      "max_bucket_count": 37
    },
    {
      "metric": "cortex_request_downstream_duration_seconds",
      "series_count": 11,
      "bucket_count": 270,
      "avg_bucket_count": 24.545454545454547,
      "min_bucket_count": 1,
      "max_bucket_count": 80
    },
    {
      "metric": "cortex_request_duration_seconds",
      "series_count": 226,
      "bucket_count": 5678,
      "avg_bucket_count": 25.123893805309734,
      "min_bucket_count": 1,
      "max_bucket_count": 75
    }
  ]
}
```

## Limit the number of buckets for a metric

To control costs, you can limit the number of buckets used for a metric. For more information, refer to [Limit the number of buckets](/docs/mimir/next/send/native-histograms/#limit-the-number-of-buckets) in the Mimir documentation.