> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dari.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage And Budgets

> See what your app used, and the caps users can set.

## Read Usage

```ts Node theme={null}
import { usage } from "@mupt-ai/dari-gateway/link/client";

const report = await usage({
  gatewayUrl: DARI_GATEWAY_URL,
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
  refreshToken,
  tags: { run: "r1" },              // optional filter
  since: new Date(Date.now() - 86_400_000),
  groupByTag: "trial",              // optional: totals per trial
});
```

```python Python theme={null}
import requests
from datetime import datetime, timedelta, timezone

report = requests.get(f"{DARI_GATEWAY_URL}/v1/link/usage",
    params={
        "tag": "run=r1",              # optional filter
        "since": (datetime.now(timezone.utc) - timedelta(days=1)).isoformat(),
        "group_by": "tag:trial",      # optional: totals per trial
    },
    headers={"Authorization": f"Bearer {access_token}"}).json()
```

```go Go theme={null}
query := url.Values{
	"tag":      {"run=r1"}, // optional filter
	"since":    {time.Now().Add(-24 * time.Hour).UTC().Format(time.RFC3339)},
	"group_by": {"tag:trial"}, // optional: totals per trial
}
endpoint := dariGatewayURL + "/v1/link/usage?" + query.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
report, err := http.DefaultClient.Do(req) // the body is the report, as JSON
```

```bash cURL theme={null}
curl "$DARI_GATEWAY_URL/v1/link/usage?tag=run%3Dr1&since=2026-01-01T00:00:00Z&group_by=tag:trial" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The Python, Go, and cURL tabs send an access token. One call makes it from the refresh token you saved, and it lasts an hour: see [Refresh](https://docs.dari.dev/link/reference/http.md#refresh). The Node client makes and keeps it for you.

```json theme={null}
{
  "requests": 7, "errors": 1,
  "input_tokens": 70, "output_tokens": 14,
  "cache_read_tokens": 28, "cache_write_tokens": 2,
  "by_model": [{ "model": "openai/gpt-5.5", "thinking": "high", "requests": 4 }],
  "by_tag": [{ "value": "7", "requests": 3 }]
}
```

One request's usage: `GET /v1/link/usage/requests/<X-Request-Id>`.

## Tag Requests

Send a header, or set `tags` on a [child token](https://docs.dari.dev/link/sandboxes.md):

```
X-Dari-Tags: run=r1,trial=7
```

## Budgets

A user can cap the tokens your app may use per 5 hours and per week (for example, "500K tokens / week"). One cap covers the whole connection: all its plans and API keys together. Users set it on the connections page (`/v1/link/connections`). It can also be set with a key: on a self-hosted gateway, the operator's gateway key; on hosted Dari, the user's own personal key.

```bash theme={null}
curl -X PUT $DARI_GATEWAY_URL/v1/link/grants/<grant id>/budget \
  -H "Authorization: Bearer $DARI_GATEWAY_KEY" \
  -d '{"budget": [{"window_minutes": 10080, "max_tokens": 500000}]}'
```

`window_minutes` is `300` or `10080`; `[]` removes the cap.

Tokens are counted the way usage above reports them: input + output + cache read + cache write, for every request of the connection, child tokens included. Windows roll: a week means the last 7 days. Each request is checked before it runs, so the one that crosses the cap still finishes. After that you get:

```
424 grant_budget_exhausted
Retry-After: 3600
```

`resets_at` is when enough of the window's oldest requests roll off to bring it back under the cap. [`grant`](https://docs.dari.dev/link/manage-connections) shows `used_tokens` for each window.

## Plan And Key Limits

A user can also limit each plan and API key a connection uses.

* **A plan** takes `max_percent`: the share of its quota past which the connection stops using it. While any of the plan's 5-hour or weekly windows, as its provider last reported, is at `max_percent` used, the plan stops serving the connection until that window resets. The provider's count covers every use of the plan, the user's own included, so the rest stays the user's. A plan whose provider has reported no usage yet is never at its limit.
* **An API key** takes `monthly_usd`: what the connection may spend on it in a calendar month (UTC), as its provider charged. At the limit it stops serving the connection until the month ends.

A plan limited in dollars before shares existed keeps that `monthly_usd` limit, counted at API prices, until it is changed.

The rest keep serving. Users set these on the connections page, or with the same key as budgets:

```bash theme={null}
curl -X PUT $DARI_GATEWAY_URL/v1/link/grants/<grant id>/limits \
  -H "Authorization: Bearer $DARI_GATEWAY_KEY" \
  -d '{"limits": [{"credential_id": "<plan id>", "max_percent": 70}, {"credential_id": "<key id>", "monthly_usd": 50}]}'
```

`[]` removes them. `GET /v1/link/grants` shows each plan and key's `spend`: `spent_usd` this month, `used_percent` for a plan's most-used window, and `reached` with `resets_at` while it is at its limit. When every plan and key of a connection is at its limit, requests get `424 grant_budget_exhausted` with `resets_at` when the first comes back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.