---
title: "Token limits API | Grafana Cloud documentation"
description: "Read and manage Grafana Assistant monthly token limits with the HTTP API."
---

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

# 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](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis).

## 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**

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

```json
{
  "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"
  }
}
```

Expand table

| 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**

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

```bash
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.

Expand table

| 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. |

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

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

**Response**

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

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

**Examples**

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

```bash
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**

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

```bash
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**

Expand table

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

Send a JSON request body.

Expand table

| 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. |

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

```json
{
  "perUserMtok": 75
}
```

**Response**

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

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

**Examples**

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

```bash
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**

Expand table

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

**Response**

A successful deletion returns HTTP 204 with no response body.

**Examples**

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

```bash
TEAM_UID="abc123"

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