Skip to main content
Every run costs credits. Budgets cap that spend, and usage pages show where it went.

What a run costs

On xpander cloud, one credit is one cent. A turn costs: A skill call is one action the agent runs on a skill through xpander. Planning and thinking steps are free, and a coding agent’s own steps, such as Bash, Read and Edit in Claude Code, are not skill calls. On a key you brought (an agent-level credential or the organization’s key under Platform > AI governance > Models) or a person’s own Claude plan, model tokens are measured but not charged. The run pays for session hours instead, on top of the wake and skill calls. Session time is counted by the minute, and only minutes with a model call count, so idle time between calls is free. On a self-hosted installation, usage is measured and never charged. New organizations start with a grant of credits. The balance is the chip in the top bar. A turn in flight always finishes, even below zero. The next turn is refused until an admin tops up. Members see the balance but cannot buy credits.

Budgets on an agent

An agent’s owner sets budgets on that agent, and admins on any agent, in Agent settings > Advanced > Budget. A budget is a cap in credits with thresholds. Each threshold is a percentage with an action, Warn or Stop. A turn’s spend also counts toward the budget of the person who started it and toward the organization’s limit, which admins set on Budgets (person budgets on the Members tab, the Organization limit, monthly). Maximum agent budget there caps how high anyone may set an agent or turn budget.
Budgets page with an overview and tabs for Groups, Members, API keys, Agents and End users

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

What happens at a stop threshold

A refused run names the budget it hit. Raising an agent budget lifts its block at once. A turn budget cannot be raised after the fact.
Budgets count model usage at its nominal cost, including usage on keys you brought: the agent’s Budget section says so. A budget stops a run on your own key too. In Logs, the call shows its cost in credits, and Subscription: names your key’s kind.
  • Enforcement off: agent, turn and member budgets block only while Enforce agent, turn and member budgets is on, in Budget rules on Platform > AI governance > Budgets. Off, spend and alerts continue but nothing blocks, and the agent’s budget editor says Budget limits only warn.
  • Infrastructure faults: budgets are a cost guardrail, not a security boundary. On a fault, a run proceeds rather than every agent being blocked.

Usage

system:llm-gateway-watchdog is xpander’s health check of your custom model endpoints, every 2 minutes. It costs 0 credits and counts toward no budget.
Usage page with a Credits and dollars toggle and cost by person

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

GET /v1/tasks/{task_id}/llm_usage returns tokens, 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 tokens are still counted. The record is written a few seconds after the turn ends, so an immediate call can read zeros.

Notifications

Budget alerts on the agent is the screen for on_budget: it notifies you when the agent crosses a threshold. On xpander cloud, with Budget alerts on and a channel and destination added, a notification fires once per threshold per period. On the API, an agent’s notification_settings also send run outcomes to email, Slack or a webhook: on_success and on_error (failed or stopped). These two have no screen. Set them with PATCH /v1/agents/{agent_id}. Approval requests reach their approvers separately, in xpander Chat, by email, in Slack, and on xpander cloud in Telegram or WhatsApp.

Next steps

Set organization and group budgets

Organization, group and key budgets.

Read usage and logs

Spend by person, agent and model.