---
title: "reserve"
method: POST
path: "/api/v1/budget-guard/reserve"
tags: ["budget-guard"]
---

# reserve

`POST /api/v1/budget-guard/reserve`

## Request

- Base URL: `https://cloudforbots.com`
- URL: `https://cloudforbots.com/api/v1/budget-guard/reserve`
- Auth: HTTP bearer

Call BEFORE each model call, tool call or sub-agent spawn with your estimate. Returns allowed=true and deducts it, or allowed=false with the limit that tripped. When allowed is false, stop, do not retry, and return your partial result to the user. Atomic, so parallel sub-agents cannot both slip under the cap.

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `handle` string, required: The budget handle from open_budget (looks like bg_<id>.<secret>). Pass it to every sub-agent so they all spend from the same budget.
  - `usd` number: Estimated cost of the next call in USD.
  - `tokens` integer: Estimated tokens of the next call.
  - `calls` integer: Number of calls to reserve (default 1).
  - `note` string: Short note, e.g. "web_search #12".

## Response `200`

Tool result (always includes request_id).

- object

## Other responses

- `400`: Bad JSON
- `401`: Missing or bad key
- `403`: Key limits (scopes) do not allow this tool or action
- `409`: Same Idempotency-Key still running
- `422`: Idempotency-Key reused on another route
- `429`: Over 20 requests/second for this key, or free daily limit
- `504`: Tool did not answer in time; retry with the same Idempotency-Key

---

[API](https://skmtc.dev/cloudforbots/apis/cloud-for-bots-api.md) · [All operations](https://skmtc.dev/cloudforbots/apis/cloud-for-bots-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cloudforbots/apis/cloud-for-bots-api/revisions/1afdb5648693?raw)