---
title: "Analyze metrics usage with the Prometheus API | Grafana Cloud documentation"
description: "Use the Prometheus API to query large number of active series or endpoints."
---

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

# Analyze metrics usage with the Prometheus API

If you have a large number of active series or larger endpoints (100k’s of series and bigger), the analytical Prometheus queries might run longer than the Grafana Explorer is configured to wait. In this case, as a best practice, interact directly with the [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/).

In addition, you can use the [Adaptive Metrics cost optimization tooling](/docs/grafana-cloud/cost-management-and-billing/reduce-costs/metrics-costs/control-metrics-usage-via-adaptive-metrics/) to help reduce costs.

## Before you begin

To begin with this section, you should have the [jq](https://stedolan.github.io/jq/), [curl](https://curl.se/), `sort`, and `date` command-line utilities installed on your machine. You can also use an API request tool like [Postman](https://www.postman.com/), but configuring such tools goes beyond the scope of this guide.

## Set the environment to query the API

Open a command-line shell like `bash` and set the following two variables that will be referenced in subsequent `curl` commands:

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

```bash
login="<METRICS_INSTANCE_ID>:<CLOUD_ACCESS_POLICY_TOKEN>"
url="<METRICS_INSTANCE_QUERY_ENDPOINT>"
```

Replace `<METRICS_INSTANCE_ID>` with the **User** parameter from the Prometheus endpoint **Details** page. You can navigate to the Prometheus endpoint details page from the Cloud Portal:

In the example above, the User is `18818`.

Replace `<CLOUD_ACCESS_POLICY_TOKEN>` with a token for a Cloud Access Policy with the `metrics:read` scope. To do this, follow the instructions in [Create a Cloud Access Policy](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/).

Replace `<METRICS_INSTANCE_QUERY_ENDPOINT>` with the query endpoint URL from the Prometheus endpoint **Details** page.

Once you’ve set the `login` and `url` variables, you can query the Prometheus API.

For guidance on selecting the correct base URL for Prometheus and Mimir endpoints, refer to [Query metrics using HTTP APIs](/docs/grafana-cloud/send-data/metrics/metrics-prometheus/query-http-api/).

## Fetch a list of active metrics and their cardinalities

You can fetch a list of active metrics and cardinalities using the `/query` API endpoint, which accepts a PromQL query as a parameter.

We’ll first query the API for a list of metrics, and then loop over this list, querying the API once again for an active series count for each metric.

1. Change the `now` variable to the current time:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   now=$(date +%s)
   ```
2. Run the loop using `curl`:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   curl -s -u $login $url/api/v1/label/__name__/values \
   | jq -r ".data[]" \
   | while read metric; do
       count=$(curl -s \
           -u $login \
           --data-urlencode 'query=count({__name__="'$metric'"})' \
           --data-urlencode "time=$now" \
           $url/api/v1/query \
       | jq -r ".data.result[0].value[1]")
       echo "$count $metric"
   done
   ```

This command first queries the `/api/v1/label/` metadata endpoint with the `__name__` meta-label to fetch a list of metric names. It then uses the `jq` utility to extract the `data` field from the JSON response.

Finally, the `while` loop iterates over the metrics, querying the API at `/api/v1/query` with the metric name and `count()` operator for a count of active series for each metric. The metric cardinality and metric name are then printed to `stdout`.

You can save the output to a file by appending `> metric_cardinalities.out` to the end of the command. You can then import this data into a spreadsheet for further analysis.

## Fetch a list of active series for a given metric

To further drill down into a high cardinality metric, you can fetch a list of active series for any given metric.

1. Change the `now` variable to the current time:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   now=$(date +%s)
   ```
2. Set the `metric` variable to the metric you’d like to query by replacing `<high_cardinality_metric>`:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   metric=<high_cardinality_metric>
   ```
3. Use `curl` to perform the following request against the Prometheus API:
   
   Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```bash
   curl -s \
       -u $login \
       --data-urlencode "query=$metric" \
       --data-urlencode "time=$now" \
       $url/api/v1/query \
   | jq -c ".data.result[].metric"
   ```

This command uses the Prometheus API’s [Query endpoint](https://prometheus.io/docs/prometheus/latest/querying/api/#expression-queries) to fetch a list of active time series for a given metric. To learn more about the Prometheus HTTP API, see the Prometheus [API docs](https://prometheus.io/docs/prometheus/latest/querying/api/#http-api).

## Fetch a list of all metrics

> Note
> 
> This method may report some inactive metrics.

To use the metadata API to quickly fetch a list of all metrics, perform the following HTTP request using `curl`:

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

```bash
curl -s -u $login $url/api/v1/label/__name__/values | jq -r ".data[]" | sort
```

This queries the `/api/v1/label` endpoint for metric names using the `__name__` meta-label. The result is then extracted using `jq` and sorted using the `sort` utility.

## Fetch a list of labels and their cardinalities

> Note
> 
> This method may report some inactive metrics.

To fetch a list of labels and their cardinalities (for example the number of unique `hostname` values), perform the following HTTP request using `curl`:

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

```bash
curl -s -u $login $url/api/v1/labels \
| jq -r ".data[]" \
| while read label; do
    count=$(curl -s -u $login $url/api/v1/label/$label/values \
    | jq -r ".data|length")
    echo "$count $label"
  done \
| sort -n
```

This request fetches a list of label names and then loops through them, fetching a list of label values for each label name. `jq` counts the length of the response list and the output is printed to `stdout`. The `sort` utility sorts the resulting `count label` list by label cardinality, which helps you identify the highest cardinality labels (labels with the most values).

## Fetch a list of series per value for a given label

> Note
> 
> This method may report some inactive metrics.

To fetch a list of values for a given label, and the number of active series using that value label.

First set the bash variable `label` to the name of the label you wish to query:

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

```bash
label=<LABEL NAME>
```

Then, run the following command:

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

```bash
curl -s -u $login $url/api/v1/label/$label/values \
| jq -r ".data[]" \
| while read label_value; do
    count=$(curl -s \
        -u $login \
        --data-urlencode 'query=count({'$label'=~"'$label_value'"})' \
        --data-urlencode "time=$now" \
        $url/api/v1/query \
    | jq -r ".data.result[0].value[1]")
    echo "$count $label_value"
done
```

This request fetches a list of values and then loops through them. Then the query retrieves a list of series for each label value and counts them. The output shows a list of label values and a number of series printed to `stdout`.