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

# Costs and budgets administration

> Manage budgets, spending limits and budget alerts, and read token events, cost aggregates and model prices, with a platform API key.

These admin routes (at v2, under `/api/v2/costs/admin/*`) run the Console's own cost and budget operations for a platform API key. An External App is refused with `403`, even when it holds the permission. Each write takes an `Idempotency-Key`. Every route is reachable from MCP through `forge_call_operation` in the `costs` tool group. That group is separate from the read-only `budgets` group, so a connection that selects only `budgets` never gains a budget write.

## Budgets and spending limits

Writes need `cost:manage`:

* Create a budget in the hierarchy, set a budget's limit in cents, and record a transaction against it.
* Create a budget alert at a threshold, and acknowledge one.
* Create or update a spending limit for a scope and period, turn one on or off, and remove one. Removing an unknown limit deletes nothing and still answers `200`, as in the Console.

Freezing or unfreezing a spending limit is an operator kill switch and needs `switches:use`. Each takes a reason of at least 8 characters; a shorter one is `400`, and an unknown limit is `404`. The audit record names the calling key as who acted.

Reads need `cost:read`: a budget, its alerts (all or only the pending ones), its transactions and its utilization, the spending limits of one scope, and every scope's spending limits.

The budget hierarchy reads as a tree: each budget's limit, spend in its current period, burn rate per day, days until exhausted, status and triggered alert count. Neither whole-deployment read answers part of its set because of a size limit. The spending limits list answers a page at a time, in id order, with `limit`, `cursor` and `meta.nextCursor`. The tree answers up to 200 budgets; a hierarchy with more is refused with `409 conflict`, and the Console's budget analytics tree is refused the same way. When the budget store cannot be read, the limits list answers an error and the tree, as in the Console, answers an empty tree.

## Token events, aggregates and prices

Reads need `cost:read`:

* Token events: the newest, by time range, by agent, by workflow or by chat session. Each event carries its model, provider, token counts, cost at capture, pricing snapshot and routing tier.
* Cost aggregates by agent, model or workflow, per bucket.
* Model prices: the current pricing, the latest price of a model, a model's price history, and the price in effect at a time.

The sandbox cost of one run step needs `workflows:read`. A step with no sandbox leases answers zeros, never `404`.

## What an answer never contains

An answer never names a person or an agent. Token events drop the agent, workflow, run, session, channel, trace and triggering message ids and the External App, and never carry prompt or completion content. Cost aggregates drop the agent and workflow they are keyed by. Spending limits drop their scope id. Alerts drop who acknowledged them, and transactions drop who recorded them and their description.

## Not on these routes

* The budget hierarchy as a flat list stays with the Console; the tree route above answers the same budgets.
* Recording a token event, the agent leaderboard, a chat thread's cost, cost by procedure, cache efficiency and the per-key token summary stay with the Console.

## Your own budget

Budgets cap spend at org units. One read returns the budget of the org unit your credential acts under: its own budget node, with the budgeted amount, used amount, remaining amount and percent used (all in cents). An API key acts at the deployment root; an External App acts at the root of the org unit that owns it. The list is empty when that org unit has no budget node.

### Operations

Reads:

* `GET /api/v3/me/budget-status` — [getBudgetStatus](https://docs.gloo.com/forge/reference/http-api/budgets/getStatus.md) — the budget of the caller's acting org unit

### Common workflow

```bash theme={null}
curl "$FORGE_BASE/api/v3/me/budget-status" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

Each item follows the `BudgetStatusEntry` schema: exactly `id`, `scope`, `period`, `budgetCents`, `usedCents`, `remainingCents` and `percentUsed`. The MCP server exposes the same read as `forge_get_budget_status`.


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