---
title: "Set or clear a budget"
method: POST
path: "/budgets"
tags: ["Budgets"]
---

# Set or clear a budget

`POST /budgets`

Sets, replaces, or clears one budget or limit using the same desired-state behavior as the Usage settings UI. Repeating an identical request leaves the existing state unchanged.

## Request body

- union
  - BudgetUpdateAccount — Full desired state for Account spending controls. When both thresholds are set, usageAlertThresholdUsd must be lower than serviceShutdownLimitUsd.
    - `type` 'account_spending_controls', required
    - `currency` 'USD', required
    - `period` 'billing_cycle', required
    - `usageAlertThresholdUsd` number, nullable, required
    - `serviceShutdownLimitUsd` number, nullable, required
  - BudgetUpdateWorkspace
    - `type` 'workspace_default_user_limit', required
    - `workspaceId` string, required
    - `currency` 'USD', required
    - `period` 'billing_cycle', required
    - `amountUsd` number, nullable, required
  - BudgetUpdateGroup
    - `type` 'workspace_group_limit', required
    - `workspaceId` string, required
    - `groupId` string, required
    - `currency` 'USD', required
    - `period` 'billing_cycle', required
    - `amountUsd` number, nullable, required
  - BudgetUpdateUser
    - `type` 'workspace_user_limit', required
    - `workspaceId` string, required
    - `userId` string, required
    - `currency` 'USD', required
    - `period` 'billing_cycle', required
    - `amountUsd` number, nullable, required

## Response `200`

Resulting budget configuration, or null after clearing it.

- BudgetUpdateResponse
  - `data` union, required
    - BudgetAccount
      - `type` 'account_spending_controls', required
      - `currency` 'USD', required
      - `period` 'billing_cycle', required
      - `usageAlertThresholdUsd` number, nullable, required — Notification-only threshold. Null means no usage alert is configured. When both thresholds are set, this value is lower than serviceShutdownLimitUsd.
      - `serviceShutdownLimitUsd` number, nullable, required — Threshold that suspends usage-based services. Null means no service shutdown limit is configured.
    - BudgetWorkspace
      - `type` 'workspace_default_user_limit', required
      - `workspaceId` string, required
      - `currency` 'USD', required
      - `period` 'billing_cycle', required
      - `amountUsd` number, required
    - BudgetGroup
      - `type` 'workspace_group_limit', required
      - `workspaceId` string, required
      - `groupId` string, required
      - `currency` 'USD', required
      - `period` 'billing_cycle', required
      - `amountUsd` number, required
    - BudgetUser
      - `type` 'workspace_user_limit', required
      - `workspaceId` string, required
      - `userId` string, required
      - `currency` 'USD', required
      - `period` 'billing_cycle', required
      - `amountUsd` number, required

## Other responses

- `400` — The request parameters are invalid.
- `401` — The API key is missing, malformed, unknown, revoked, or expired.
- `403` — The API key lacks the required scope or Account entitlement.
- `404` — The requested resource does not exist or is not visible to this key.
- `409` — Another update for the requested budget is in progress.
- `429` — The API key or operation exceeded its rate limit.
- `500` — The server encountered an unexpected error.
- `503` — The budget update is temporarily unavailable.

## Changes

> 8 revisions in range; 1 could not be searched.

- **2026-08-08** `c57911e5fe90` — 24 warning
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `400`
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `401`
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `403`
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `404`
  - …20 more
- **2026-07-31** `fd00f60ae053` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/replit/apis/replit-api/changes/budgets/post.md)

---

[API](https://skmtc.dev/replit/apis/replit-api.md) · [All operations](https://skmtc.dev/replit/apis/replit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/replit/replit-api/revisions/7293f5108d59/schema)