/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 needcost: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.
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 needcost: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.
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 — the budget of the caller’s acting org unit
Common workflow
BudgetStatusEntry schema: exactly id, scope, period, budgetCents, usedCents, remainingCents and percentUsed. The MCP server exposes the same read as forge_get_budget_status.
