---
title: "Update Organization Budget"
method: PATCH
path: "/v1/organizations/me/budgets/{budget_id}"
tags: ["organization-budgets"]
---

# Update Organization Budget

`PATCH /v1/organizations/me/budgets/{budget_id}`

Change a budget's label, figure or period.

Every ceiling naming it is held to the new figure from here on, which is the
point of naming a budget rather than typing an amount per place it applies.

## Path parameters

- `budget_id` string, required

## Request body

- OrganizationBudgetUpdate — Replace a budget's label, figure and period. Every field is optional and keyed on ``model_fields_set``, matching ``PATCH /v1/budgets/{id}``'s own: an *omitted* field is left alone, and an explicit null clears it, so sending ``max_budget: null`` takes a budget back to uncapped, which is what the dashboard's dialog does. The period pair is still mutually exclusive, and setting one does not clear the other, which is why :func:`_require_single_period_source` re-checks the *resulting* pair rather than the submitted one.
  - `budget_duration_sec` integer, nullable — Seconds between resets, counted from the last one. Mutually exclusive with reset_alignment
  - `max_budget` number, nullable — Maximum spend in USD over one period; null caps nothing
  - `name` string, nullable — Admin-facing label for the budget
  - `request_limit` integer, nullable — Maximum requests over one period; null caps nothing. Independent of max_budget
  - `reset_alignment` 'calendar_day' | 'calendar_week' | 'calendar_month', nullable — Reset on a UTC calendar boundary instead of a fixed number of seconds, which is the only way to express a calendar month. Mutually exclusive with budget_duration_sec
  - `token_limit` integer, nullable — Maximum tokens over one period; null caps nothing. Independent of max_budget

## Response `200`

Successful Response

- OrganizationBudgetPublic — One of the organization's budgets, and how much of its own config names it. Carries no spend rollup. ``BudgetResponse`` on the deployment surface sums ``users.spend`` over the gateway's ``users`` table, which is deployment-wide and has no tenancy column, so the same figure here would be a cross-tenant read. What an organization's own spend is, is a question for Usage. ``ceiling_count`` is the organization-relevant fact instead: how many of its ceilings this budget currently holds, which is what makes a delete refuse.
  - `budget_duration_sec` integer, nullable, required
  - `budget_id` string, required
  - `ceiling_count` integer, required
  - `created_at` string, required
  - `max_budget` number, nullable, required
  - `name` string, nullable, required
  - `organization_id` string, uuid, required
  - `request_limit` integer, nullable, required
  - `reset_alignment` string, nullable, required
  - `token_limit` integer, nullable, required
  - `updated_at` string, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-02** `1be78e895028` — 4 info
  - added the new optional request property `request_limit`
  - added the new optional request property `token_limit`
  - added the required property `request_limit` to the response with the `200` status
  - added the required property `token_limit` to the response with the `200` status
- **2026-08-31** `1a5cf829e593` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mozilla-ai/apis/otari/changes/v1/organizations/me/budgets/:budget_id/patch.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc.dev/mozilla-ai/apis/otari/revisions/80c117c36f36?raw)