Platform

Assistant

SDK

HTTP API

Token limits

Grafana Cloud

Token limits API

Use token limits to control how many LLM tokens your Grafana Cloud stack, users, service accounts, and teams can consume per month. Token limits help you manage costs and distribute capacity across teams.

All token limit values are in millions of tokens (Mtok). Requested limits must stay within your stack’s allowed limits. Requests that exceed those limits return HTTP 400.

When a user or service account exceeds their token limit, Assistant rejects new requests until the next calendar month.

Examples use the base URL and service account token described in Grafana Assistant HTTP API reference.

Get token limits

Retrieve the current token limit configuration for the stack, including team overrides.

Endpoint

GET /usage/tokens/limits

Permissions

grafana-assistant-app.usage:write

Request

No parameters required.

Response

{
  "status": "success",
  "data": {
    "stackTotalMtok": 500,
    "perUserDefaultMtok": 50,
    "serviceAccountPoolMtok": 100,
    "teams": [
      {
        "teamUid": "abc123",
        "perUserMtok": 75,
        "updatedAt": "2025-11-15T12:00:00Z",
        "updatedBy": "sa-5594@serviceaccount.grafana"
      }
    ],
    "updatedAt": "2025-11-15T12:00:00Z",
    "updatedBy": "sa-5594@serviceaccount.grafana"
  }
}

Field	Description
`stackTotalMtok`	Monthly token budget for the entire stack.
`perUserDefaultMtok`	Default monthly per-user limit. Applies to users without a team override.
`serviceAccountPoolMtok`	Monthly token budget shared across all service accounts. API consumers using service account tokens draw from this pool.
`teams`	Team-level per-user overrides. Users in multiple teams receive the highest cap among their teams.

Examples

curl -X GET "${ASSISTANT_API_URL}/usage/tokens/limits" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"

Set token limits

Replace the stack’s token limit configuration. Omit a field to clear that override and use the default for your plan.

Endpoint

PUT /usage/tokens/limits

Permissions

grafana-assistant-app.usage:write

Request

Send a JSON request body.

Field	Required	Description
`stackTotalMtok`	No	Monthly token budget for the entire stack. Must be positive when present.
`perUserDefaultMtok`	No	Default monthly per-user limit. Must be positive when present.
`serviceAccountPoolMtok`	No	Monthly token budget for service accounts. Must be positive when present.

{
  "stackTotalMtok": 500,
  "perUserDefaultMtok": 50,
  "serviceAccountPoolMtok": 100
}

Response

{
  "status": "success",
  "data": {
    "stackTotalMtok": 500,
    "perUserDefaultMtok": 50,
    "serviceAccountPoolMtok": 100,
    "updatedAt": "2025-11-15T12:00:00Z",
    "updatedBy": "sa-5594@serviceaccount.grafana"
  }
}

Examples

curl -X PUT "${ASSISTANT_API_URL}/usage/tokens/limits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "stackTotalMtok": 500,
    "perUserDefaultMtok": 50,
    "serviceAccountPoolMtok": 100
  }'

Reset token limits

Remove all stack-level token limit overrides. The defaults for your plan remain in effect.

Endpoint

DELETE /usage/tokens/limits

Permissions

grafana-assistant-app.usage:write

Request

No parameters required.

Response

A successful reset returns HTTP 204 with no response body.

Examples

curl -X DELETE "${ASSISTANT_API_URL}/usage/tokens/limits" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"

Set a team token limit

Set the per-user monthly token limit for members of a Grafana team. Users in multiple teams receive the highest cap among their teams.

Endpoint

PUT /usage/tokens/limits/teams/{teamUid}

Permissions

grafana-assistant-app.usage:write

Request

Parameter	Required	Description
`teamUid`	Yes	The Grafana team UID.

Send a JSON request body.

Field	Required	Description
`perUserMtok`	Yes	Monthly per-user token limit for members of this team. Use `0` for an unlimited per-user cap only if your stack allows unlimited per-user usage. Otherwise, the request returns HTTP 400.

{
  "perUserMtok": 75
}

Response

{
  "status": "success",
  "data": {
    "teamUid": "abc123",
    "perUserMtok": 75,
    "updatedAt": "2025-11-15T12:00:00Z",
    "updatedBy": "sa-5594@serviceaccount.grafana"
  }
}

Examples

TEAM_UID="abc123"

curl -X PUT "${ASSISTANT_API_URL}/usage/tokens/limits/teams/${TEAM_UID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "perUserMtok": 75
  }'

Remove a team token limit

Remove the per-user token limit for a team. Affected users fall back to the stack’s default per-user limit.

Endpoint

DELETE /usage/tokens/limits/teams/{teamUid}

Permissions

grafana-assistant-app.usage:write

Request

Parameter	Required	Description
`teamUid`	Yes	The Grafana team UID.

Response

A successful deletion returns HTTP 204 with no response body.

Examples

TEAM_UID="abc123"

curl -X DELETE "${ASSISTANT_API_URL}/usage/tokens/limits/teams/${TEAM_UID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"