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

# open budget

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

## Request

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

Open a hard budget for one agent run before it starts: max dollars, tokens, calls and/or wall-clock seconds. Returns a handle. Give the handle to every sub-agent; they all draw from the same ledger, so one runaway loop or fork cannot exceed the run cap.

## Headers

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

## Request body

- object
  - `label` string: What this run is for, e.g. "nightly code cleanup".
  - `max_usd` number: Dollar cap for the whole run (your own estimates per call).
  - `max_tokens` integer: Token cap (input + output) for the whole run.
  - `max_calls` integer: Cap on model/tool calls for the whole run.
  - `max_seconds` integer: Wall-clock cap in seconds from now.
  - `ttl_hours` integer: Handle lifetime (free max 24, Pro max 168). Default 24.
  - `mode` 'shadow' | 'enforce': shadow = watch only: track spend and flag where the cap WOULD have stopped the run, never block (free). enforce = return allowed=false at the cap (Pro). Default: enforce on Pro, shadow on free.

## 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)