Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Metricsbreadcrumb arrow Prometheus metricsbreadcrumb arrow Query metrics using HTTP APIs
Grafana Cloud

Query metrics using HTTP APIs

Use HTTP APIs to query and troubleshoot your Grafana Cloud Metrics data without using Grafana Explore. This is useful when you need to run long-running queries, automate diagnostics, or call Mimir-specific endpoints.

Before you begin

Ensure you have the following:

  • A Grafana Cloud access policy token with metrics:read scope.
  • curl installed.

Find your metrics endpoints in the Cloud Portal

You find your metrics endpoints in the Cloud Portal:

  1. Sign in to the Cloud Portal.
  2. Open your stack.
  3. In the Prometheus card, click Details.

From the details page, copy the values you need:

  • The query endpoint URL.
  • The remote write endpoint URL.
  • The user value for the endpoint (your metrics instance ID).

Authenticate to the APIs

Grafana Cloud Metrics uses basic authentication for these APIs:

  • Username: your metrics instance ID (the endpoint user value).
  • Password: your Grafana Cloud access policy token.

For example, set a LOGIN variable:

Bash 
LOGIN="<METRICS_INSTANCE_ID>:<CLOUD_ACCESS_POLICY_TOKEN>"

Choose the correct base URL

Grafana Cloud Metrics exposes multiple base URLs. The correct one depends on which API you call.

Use your Grafana stack URL for Grafana-proxied endpoints

Some endpoints are accessed through your Grafana stack URL and include a data source ID in the path. For example, the rules endpoint can use a URL in this form:

https://<YOUR_GRAFANA_STACK_URL>/api/prometheus/<PROMETHEUS_DATASOURCE_UID>/api/v1/rules

In this example, <PROMETHEUS_DATASOURCE_UID> can be grafanacloud-prom.

Note

This endpoint pattern depends on your Grafana stack URL and the Prometheus data source UID. If you use a different data source, replace grafanacloud-prom with your data source UID.

Use the query endpoint for Prometheus HTTP API endpoints

Use the query endpoint from the Cloud Portal details page as the base URL when you call Prometheus HTTP API endpoints such as:

  • GET /api/v1/query
  • GET /api/v1/label/{label}/values
  • GET /api/v1/labels

For example:

Bash 
QUERY_URL="<METRICS_INSTANCE_QUERY_ENDPOINT>"

curl -s -u "$LOGIN" \
  --data-urlencode 'query=up' \
  "$QUERY_URL/api/v1/query"

Use the Mimir Prometheus HTTP prefix for Mimir-only endpoints

The Grafana Mimir documentation refers to a <prometheus-http-prefix> for many endpoints. For details, refer to Grafana Mimir HTTP API. In Grafana Cloud Metrics, you can derive that prefix from your remote write endpoint:

  1. Start with the remote write endpoint URL.
  2. Remove the /api/prom/push suffix.
  3. Add the /prometheus suffix.

Your result resembles https://prometheus-us-central1.grafana.net/prometheus.

Use this prefix for Mimir-only endpoints, such as the cardinality APIs:

Bash 
PROMETHEUS_HTTP_PREFIX="<PROMETHEUS_HTTP_PREFIX>"

curl -s -u "$LOGIN" \
  "$PROMETHEUS_HTTP_PREFIX/api/v1/cardinality/label_names"

Note

Some Grafana Mimir HTTP API endpoints are not available in Grafana Cloud Metrics, or use different base URLs. If an endpoint returns an error, confirm you are using the correct base URL and that the endpoint is supported in your Grafana Cloud environment.

See also