Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Logsbreadcrumb arrow Authenticate to query Cloud Logs
Grafana Cloud

Authenticate to query Cloud Logs

Use the Loki HTTP API to query and troubleshoot your Grafana Cloud Logs data without using Grafana Explore. This is useful when you need to automate diagnostics, run long-running queries, or integrate log queries into your own tooling.

Before you begin

Ensure you have the following:

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

Find your Loki endpoint in the Cloud Portal

You find your Loki endpoint URL and User ID in the Cloud Portal:

  1. Sign in to the Cloud Portal.

  2. Open your stack.

  3. In the Loki card, click Details.

  4. From the details page, copy the values you need:

    • The Loki URL.
    • The User value for the endpoint (your Loki instance ID, also called the tenant ID).

For more information, refer to Find instance endpoints.

Note

Grafana Cloud URLs use one of two formats depending on when your region was created. If you need to construct a URL manually instead of copying it from the portal, refer to Determine Grafana Cloud URLs based on region.

Create an access policy and token

To query Cloud Logs using the HTTP API, you need a Grafana Cloud access policy token with the logs:read scope.

For the full procedure to create an access policy and generate a token, refer to Create access policies and tokens.

Authenticate to the API

Grafana Cloud Logs uses HTTP Basic Authentication for the Loki HTTP API:

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

For example, set a LOGIN variable:

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

Then use it with curl -u to query logs:

Bash 
curl -s -u "$LOGIN" \
  -G "<LOKI_URL>/loki/api/v1/query_range" \
  --data-urlencode 'query={job="varlogs"}' | jq

Note

Some Cloud Logs API endpoints (such as the self-serve settings API) show examples using an Authorization: Bearer <LOKI_INSTANCE_ID>:<CLOUD_ACCESS_POLICY_TOKEN> header instead of curl -u. Both forms authenticate the same way; curl -u is the more common convention and is used throughout this page.

Common errors

  • 401 Unauthorized: The Loki instance ID (username) is incorrect, or the access policy token is invalid, expired, or revoked.
  • 403 Forbidden: The access policy associated with the token doesn’t include the logs:read scope, or a label policy on the access policy excludes the labels in your query.

Next steps