Documentation Grafana Cloud Cost Management and Billing Analyze and reduce costs Logs Query limit policies

Configure Loki query limit policies

Loki query limit policies provide fine-grained control over how users query your Grafana Cloud Logs data. You can configure these policies as attributes on access policies to limit query result sizes.

When a query exceeds a configured limit, users receive meaningful error messages that explain why the query was rejected and how to adjust it.

How query limit policies work

Query limit policies are applied as lokiQueryPolicy attributes on access policies. When a user makes a request using a token associated with an access policy that has query limits configured, Loki validates the entire time period of the query against those limits before execution.

Use cases

Use Loki query limit policies to:

• Prevent expensive queries that could impact system stability
• Control the volume of data returned by queries

Available controls

The following table describes the available query limit controls, their valid values, and the error messages users see when limits are exceeded.

Before you begin

Before you configure query limit policies, ensure you have:

• An API token with accesspolicies:read and accesspolicies:write scopes
• The stack ID for your Grafana Cloud stack

For more information about using the Grafana Cloud API, refer to the Cloud API documentation.

Create an API token with the required scopes

To manage Loki query limit policies using the API, you need a token with permissions to read and write access policies.

To create an API token with the required scopes:

1. Sign in to your Grafana Cloud account at Grafana Cloud.

2. Select your organization from the dropdown at the top of the page.

3. In the left navigation menu, under Security, select Access Policies.

4. Click Create access policy.

5. Enter a Display name for the access policy (for example, Manage Access Policies).

6. From the Realm dropdown, select your organization or the specific stack you want to manage.

7. Under Scopes, select the following permissions:

   • Access Policies: Read (accesspolicies:read)
   • Access Policies: Create and edit (accesspolicies:write)

   If you don’t see these scopes, click Add scope and search for them.

8. Click Create to save the access policy.

9. On the access policy details page, click Add token.

10. Enter a Display name for the token.

11. Optionally, set an Expiration date for the token.

12. Click Create.

13. Copy the generated token and store it securely.

    Warning

    The token is only displayed once. Copy and save it in a secure location, such as a password manager.

For more information about creating access policies and tokens, refer to Create access policies and tokens.

Find your stack ID

To find your Grafana Cloud stack ID:

1. Sign in to your Grafana Cloud account at Grafana Cloud.
2. Select your organization from the menu at the top of the page.
3. In the left navigation menu, click Stacks.
4. Locate your stack and note the ID value displayed in the stack details.

List access policies

To view your current access policies and their query limit configurations, run the following command:

Bash Copy

curl --location "https://grafana.com/api/v1/accesspolicies?region=<REGION>" \
    --header "Authorization: Bearer $GRAFANA_TOKEN" \
    --header "Accept: application/json" \
| jq

Replace <REGION> with your Grafana Cloud region (for example, us, eu, or au).

Create an access policy with Loki query limits

To create a new access policy with Loki query limit controls:

1. Set your API token as an environment variable:

   Bash Copy

   export GRAFANA_TOKEN=<YOUR_API_TOKEN>

2. Run the following command to create the access policy:

   Bash Copy

   curl --location --request POST 'https://grafana.com/api/v1/accesspolicies?region=<REGION>' \
       --header "Authorization: Bearer $GRAFANA_TOKEN" \
       --header 'Content-Type: application/json' \
       --data-raw '{
         "name": "my-access-policy",
         "displayName": "My Access Policy",
         "scopes": [
           "logs:read"
         ],
         "realms": [{
           "type": "stack",
           "identifier": "<STACK_ID>"
         }],
         "attributes": {
           "lokiQueryPolicy": {
               "maxQueryBytesRead": "500MB"
           }
         }
     }'

   Replace:

   • <REGION> with your Grafana Cloud region
   • <STACK_ID> with your stack identifier

Modify a Loki query limit policy

To update the query limits on an existing access policy:

1. Obtain the access policy ID from the list of access policies.

2. Run the following command to update the policy:

   Bash Copy

   curl --location --request POST 'https://grafana.com/api/v1/accesspolicies/<ACCESS_POLICY_ID>?region=<REGION>' \
       --header "Authorization: Bearer $GRAFANA_TOKEN" \
       --header 'Content-Type: application/json' \
       --data-raw '{
         "attributes": {
           "lokiQueryPolicy": {
               "maxQueryBytesRead": "1GB"
           }
         }
       }'

   Replace:

   • <ACCESS_POLICY_ID> with the ID of the access policy to update
   • <REGION> with your Grafana Cloud region

Remove a Loki query limit from an access policy

To remove a specific query limit from an access policy, set the limit value to null:

Bash Copy

curl --location --request POST 'https://grafana.com/api/v1/accesspolicies/<ACCESS_POLICY_ID>?region=<REGION>' \
    --header "Authorization: Bearer $GRAFANA_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "attributes": {
        "lokiQueryPolicy": {
            "maxQueryBytesRead": null
        }
      }
    }'

This removes the maxQueryBytesRead limit while leaving other configured limits in place.