---
title: "Cap what one unit of agent work may spend"
method: PUT
path: "/v1/runs/{runId}/budget"
tags: ["Effects"]
---

# Cap what one unit of agent work may spend

`PUT /v1/runs/{runId}/budget`

## Request

- Base URL: `https://ratchetgate.com`
- URL: `https://ratchetgate.com/v1/runs/{runId}/budget`
- Auth: HTTP bearer

Opens or adjusts a wallet for a run id. The gate refuses any effect that would carry the run past this total — before the money moves, which is the only moment refusing is still cheap. Unlike the daily budgets this never resets: a task is not a day. Lowering a limit below what is already spent claws nothing back; it means nothing further may be spent. Counts what callers declare in estimated_cost_micros, so it is only ever as good as what they declare.

## Path parameters

- `runId` string, required

## Request body

- object
  - `limit_micros` integer, required: Total this run may spend at vendors, in micro-USD. 1000000 = $1.

## Response `200`

Default Response

- object

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `402`: Insufficient prepaid credit.
- `403`: Scope, policy, or budget refusal.
- `404`: Not found.
- `409`: Conflicting state or idempotency-key reuse.
- `413`: Payload too large.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/ratchetgate/apis/ratchet-api.md) · [All operations](https://skmtc.dev/ratchetgate/apis/ratchet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ratchetgate/apis/ratchet-api/revisions/5712f33c692f?raw)