---
title: "Set execution budgets"
method: PATCH
path: "/v1/billing/budgets"
---

# Set execution budgets

`PATCH /v1/billing/budgets`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/billing/budgets`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Replaces the caller organization's advisory execution budget and optional hard execution-spend cap for the current UTC month. Values are exact whole cents encoded as integer microdollars. The expected budget-policy revision prevents a stale editor overwriting a newer choice, and Idempotency-Key makes retrying one intent safe. Null turns that setting off. This command records desired state durably; billing.reconcile advances it to PostgreSQL, and reads remain pending until PostgreSQL confirms it. It never changes automatic top-up authority, purchases credit, or counts subscription payments as execution usage.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `advisoryBudget` object, nullable, required
    - `currency` 'USD', required
    - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
    - `scale` 6, required
  - `expectedRevision` integer, required
  - `hardCap` object, nullable, required
    - `currency` 'USD', required
    - `microdollars` string, required: A canonical nonnegative integer multiple of 10,000 microdollars, no greater than 9,223,372,036,854,770,000.
    - `scale` 6, required

## Response `200`

Set execution budgets

- object
  - `budgetPolicy` object, required
    - `desired` object, required
      - `advisoryBudget` object, nullable, required
        - `currency` 'USD', required
        - `microdollars` string, required
        - `scale` 6, required
      - `hardCap` object, nullable, required
        - `currency` 'USD', required
        - `microdollars` string, required
        - `scale` 6, required
    - `desiredRevision` integer, required
    - `effectiveRevision` integer, required
    - `pending` boolean, required
  - `freshness` object, required
    - `kind` 'authoritative', required

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing, test_to_live_escalation.
- `409`: Problem document. Possible codes at this status: idempotency_key_reused, project_archived, revision_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)