Skip to main content
A budget check made after an action runs can only report an overspend. A reservation holds the estimated cost before the action runs, so concurrent agents cannot all pass the same check and overshoot the budget together. The Python SDK does this for you when you use RemoteCostBackend. Call the endpoint directly if you are integrating from another language.

​
POST /api/v1/budgets/reserve

Atomically checks the caller’s organization monthly budget and, when group_id is set, that group’s budget, then holds estimated_cost_usd against both for 15 minutes. Requires an API key or session in an organization context.

​
Request

​
Response: 201 Created

remaining_usd is the smallest headroom left across the budgets that were checked, or null when neither has a limit configured.

​
Response: 402 Payment Required

The hold would exceed a budget. Nothing is reserved.
budget_type is organization_monthly (with error: "monthly_budget_exceeded") or group. spent is the projected total including this request.

​
Other errors

​
Settling a reservation

Send the reservation_id on the matching ledger entry when you ingest it. Ingest swaps the held estimate for the entry’s actual cost_usd, so the spend is not counted twice. A hold that is never settled stops counting against the budget once its 15 minutes are up.