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

# Budgets and usage

> What a run costs in credits, how budgets cap an agent, a turn, a person or an organization, what happens when one is reached, where usage is shown, and how the outcome of a run is reported.

## What a run costs

On xpander's cloud, usage is paid in credits; one credit is one cent. A turn costs one credit when the agent wakes, one credit per skill call, and the model's tokens at the provider's public price plus a quarter, per model. Calls on a key you brought, whether an agent-level credential or the organization's key under Platform > AI governance > Models, are measured the same way but not charged. Every new organization starts with a grant of credits; the balance is the chip in the top bar, and a task's cost grows on its card as it runs. A turn in flight always finishes, even below zero; the next one is refused until an admin tops up, and members see the balance but cannot buy. On a self-hosted installation usage is measured and shown identically and never charged.

## Budgets

A budget is a cap in credits with thresholds. Each threshold is a percentage with an action, **warn** or **stop**; with **Budget alerts** on, a notification fires once per threshold per period.

![Budgets page with an overview and tabs for Groups, Members, API keys, Agents and End users](https://mintcdn.com/xpanderai-099931d1/wqIIXSsh0kqA2hZ_/images/verify/platform-budgets.png?fit=max\&auto=format\&n=wqIIXSsh0kqA2hZ_\&q=85\&s=8ba6fbe191c7f88779cc3fc347960627)

Platform > AI governance > Budgets: overview and spending limits by scope. Shown with sample data.

| Budget | Set where | Resets |
| - | - | - |
| **Agent** | Agent settings > Advanced > **Per-agent budget**, "a recurring roll-up cap across every task this agent runs". Daily, weekly or monthly, several at once | At midnight UTC at the period boundary; no rollover |
| **Turn** | Agent settings > Advanced > **Per-turn budget**, a cap in credits on a single turn | Never; a depleted turn budget is final |
| **Person** | **Platform > AI governance > Budgets**, **Members** tab: a default and per-person budgets | Per period |
| **Organization** | Set by a parent organization on a sub-organization; read-only there | Per period |

A turn's spend counts toward the agent's budgets, and toward the person's. When a **stop** threshold is reached, the stop mode decides. **Finish in-flight turn**, the default, lets the running turn complete and refuses new ones. The other stop mode ends the running turn at its next model call, which ends as `stopped` with "Execution stopped: budget exceeded." A refused run says which budget it hit and to raise it or wait for the next period. Raising an agent budget lifts its block at once. A turn budget cannot be raised after the fact.

Budgets count charged model spend. On an installation where every model call runs on a key or identity you brought, usage is measured as a nominal amount but nothing is charged, so a budget reports and never stops a run. A one-credit turn budget with enforcement on did not stop turns on an install's own Bedrock identity. Use gated commands and approval rules for control there.

Agent, turn and member budgets act only while **Enforce agent, turn and member budgets** (Platform > AI governance > Budgets, under **Budgets set in agent settings**) is on. Off, spend still accrues, usage is still shown and alerts still fire, but nothing blocks a run; an agent's budget editor shows a banner while that is the case. **Maximum agent budget** in the same section caps how high anyone may set an agent or turn budget. Budgets for the organization, groups, API keys and agents are covered on [Budgets](https://docs.xpander.ai/run/llm-gateway/budgets-and-blocks.md). Budgets are a cost guardrail, not a security boundary: an infrastructure fault lets a run proceed rather than blocking every agent. Agent creators set budgets on their agents; admins set them anywhere.

## Usage

**Settings > Usage** shows what your own calls and the agent runs you started cost, with your spending limit when one applies. Admins see the organization's spend in **Platform > AI governance > Usage**, in credits or dollars (**Credits** / **\$**), grouped by person, agent, model and more, with calls tied to no person shown as **Not tied to a person** ([Usage and logs](https://docs.xpander.ai/run/llm-gateway/requests-and-costs.md)). **system:llm-gateway-watchdog** is xpander's own health check of your custom model endpoints, a small request every 2 minutes. It costs 0 credits and counts toward no budget. A task's own panel shows its tokens (input, output, cache read and cache write), cost and model.

![Usage page with a Credits and dollars toggle and cost by person](https://mintcdn.com/xpanderai-099931d1/wqIIXSsh0kqA2hZ_/images/verify/platform-usage.png?fit=max\&auto=format\&n=wqIIXSsh0kqA2hZ_\&q=85\&s=9855a794977208829643e85e966fbb68)

Platform > AI governance > Usage in credits, grouped by person. Shown with sample data.

`GET /v1/tasks/{task_id}/llm_usage` returns the token-level record of one task: `tokens` (the total), `input`, `output`, `cache_write`, `is_byok`, `cost` and `ai_model`. On a key you brought, `is_byok` is `true` and `cost` is `0.0` while the tokens are still counted. The record is written a few seconds after the turn ends; a call made within seconds of the reply can read zeros.

## Notifications

**Budget alerts** on the agent notify you when it crosses a threshold. Beyond that, an agent's `notification_settings` on the API name where the outcome of a run goes: `on_success`, `on_error` (a task that failed or was stopped) and `on_budget`. Each can go to email, Slack or a webhook, with the amount reached and the cap. The setting has no screen of its own yet; set it with `PATCH /v1/agents/{agent_id}`. Approval requests reach their named approvers separately, in Xpander Chat, by email, in Slack, Telegram or WhatsApp.


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