---
title: "Create Scoped Budget"
method: POST
path: "/v1/scoped-budgets"
tags: ["scoped-budgets"]
---

# Create Scoped Budget

`POST /v1/scoped-budgets`

Create a scoped budget.

Answers 404 when the scope names nothing, rather than creating a ceiling
that can never bind.

## Request body

- CreateScopedBudgetRequest — Request model for creating a scoped budget.
  - `budget_duration_sec` integer, nullable — Period length in seconds (e.g. 86400 for daily); null never resets
  - `max_budget` number, nullable — Maximum USD spend in the period
  - `name` string, nullable — Admin-facing label for the budget
  - `provider_key_id` string, nullable — Narrow the cap to one provider instance; null caps spend across every provider
  - `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
  - `scope_id` string, required — Id of the capped identity: an organization, workspace, membership row, or API key
  - `scope_type` 'organization' | 'workspace' | 'workspace_member' | 'org_member' | 'api_token', required — Which kind of identity this ceiling caps

## Response `200`

Successful Response

- ScopedBudgetResponse — One scoped ceiling and its live counters. Unlike ``/v1/budgets``, the counters are the row's own: a scoped ceiling is enforced against ``current_spend + reserved_spend``, so there is no rollup over users to compute.
  - `budget_duration_sec` integer, nullable, required
  - `created_at` string, required
  - `current_spend` number, required
  - `id` string, required
  - `max_budget` number, nullable, required
  - `name` string, nullable, required
  - `period_end` string, nullable, required
  - `period_start` string, nullable, required
  - `provider_key_id` string, nullable, required
  - `reserved_spend` number, required
  - `reset_alignment` string, nullable, required
  - `scope_id` string, required
  - `scope_type` string, required
  - `updated_at` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.net/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mozilla-ai/otari/revisions/2ebadef75cc8/schema)