budget-guard

reserve

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.

post/api/v1/budget-guard/reserve

Request

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

Headers

Idempotency-Keystring

Makes the call safe to retry; the same key returns the stored reply for 24h.

X-Request-Idstring

Request body

handlestring 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.

usdnumber

Estimated cost of the next call in USD.

tokensinteger

Estimated tokens of the next call.

callsinteger

Number of calls to reserve (default 1).

notestring

Short note, e.g. "web_search #12".

Response

Tool result (always includes request_id).

object required

Changes

No recorded changes to this operation across all 1 revision of this API.