> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # Create budget > Creates an organization-owned budget. The scope discriminates which resource the budget covers, across all seven scope types (organization / team / project / virtual_key / principal / group / attributed_user). `group` budgets are per-member allowances and `attributed_user` budgets are per-end-user templates; both require a deployment with the ClickHouse spend ledger (`group_budget_requires_clickhouse` otherwise). `provider_key` optionally pins the budget to one model provider. `cycle_anchor_at` optionally phases the window off a chosen instant instead of the calendar, for budgets that have to line up with a billing date. A `team`, `project` or `group` budget that none of the organization's active keys can produce traffic for is refused with `gateway_budget_scope_unreachable`, since it would never spend and never block; send `allow_unreachable` to keep it anyway, and note that an organization with no active keys is never refused. Send `Idempotency-Key` to make a retry safe. ## OpenAPI ````yaml POST /api/gateway/v1/budgets openapi: 3.1.0 info: title: LangWatch API version: 1.0.0 description: LangWatch openapi spec servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/gateway/v1/budgets: post: tags: - Budgets summary: Create budget description: >- Creates an organization-owned budget. The scope discriminates which resource the budget covers, across all seven scope types (organization / team / project / virtual_key / principal / group / attributed_user). `group` budgets are per-member allowances and `attributed_user` budgets are per-end-user templates; both require a deployment with the ClickHouse spend ledger (`group_budget_requires_clickhouse` otherwise). `provider_key` optionally pins the budget to one model provider. `cycle_anchor_at` optionally phases the window off a chosen instant instead of the calendar, for budgets that have to line up with a billing date. A `team`, `project` or `group` budget that none of the organization's active keys can produce traffic for is refused with `gateway_budget_scope_unreachable`, since it would never spend and never block; send `allow_unreachable` to keep it anyway, and note that an organization with no active keys is never refused. Send `Idempotency-Key` to make a retry safe. operationId: postApiGatewayV1Budgets parameters: - name: Idempotency-Key in: header required: false description: >- A caller-chosen key, 8 to 255 characters, that makes this create safe to retry. The first request to use a key runs normally and its response is stored for 24 hours. A later request with the same key and the same body is not executed again: it returns the stored response, marked with `X-Idempotent-Replay: true`. The same key with a different body is refused 409 `idempotency_error`, as is a retry sent while the original is still running. Only successful responses are stored, so a create that failed can simply be retried with the same key. schema: type: string minLength: 8 maxLength: 255 requestBody: required: true content: application/json: schema: type: object properties: scope: oneOf: - type: object properties: kind: type: string const: organization organization_id: type: string required: - kind - organization_id - type: object properties: kind: type: string const: team team_id: type: string required: - kind - team_id - type: object properties: kind: type: string const: project project_id: type: string required: - kind - project_id - type: object properties: kind: type: string const: virtual_key virtual_key_id: type: string required: - kind - virtual_key_id - type: object properties: kind: type: string const: principal principal_user_id: type: string required: - kind - principal_user_id - type: object properties: kind: type: string const: group group_id: type: string required: - kind - group_id - type: object properties: kind: type: string const: attributed_user anchor_virtual_key_id: type: string anchor_project_id: type: string required: - kind name: type: string minLength: 1 maxLength: 128 description: type: string window: type: string enum: - minute - hour - day - week - month - total - manual limit_usd: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d+)?$ on_breach: type: string enum: - block - warn timezone: type: - string - 'null' provider_key: type: - string - 'null' external_id: type: - string - 'null' minLength: 1 maxLength: 128 metadata: type: object propertyNames: type: string minLength: 1 maxLength: 64 additionalProperties: type: string maxLength: 500 cycle_anchor_at: type: string format: date-time description: >- Phases the budget's cycle off this instant instead of the calendar, so a `month` budget anchored 2026-01-17T09:00:00Z starts a fresh period every 17th at 09:00 UTC. Omit for calendar alignment, which is the default and unchanged behaviour. A month cycle anchored past the 28th clamps into shorter months and springs back: anchored on the 31st gives Feb 28, then Mar 31. Immutable after create, since moving it would redraw periods the budget has already reported and enforced on. Rejected with `gateway_budget_cycle_anchor_invalid` on `total` and `manual`, which do not cycle. allow_unreachable: type: boolean description: >- Keeps a `team`, `project` or `group` budget that no active key can produce traffic for, which is otherwise refused with `gateway_budget_scope_unreachable`. Send it to provision ahead of the keys that will use the budget. An organization with no active keys is never refused, so this is not needed during first setup. required: - scope - name - window - limit_usd responses: '201': description: Budget created headers: X-Idempotent-Replay: description: >- Present and `true` only when this body came from a stored response rather than a fresh execution. Absent on the first use of a key, and on every request that carries no key. schema: type: string enum: - 'true' content: application/json: schema: type: object properties: budget: type: object properties: id: type: string organization_id: type: string scope_type: type: string enum: - organization - team - project - virtual_key - principal - group - attributed_user scope_id: type: string name: type: string description: type: - string - 'null' window: type: string enum: - minute - hour - day - week - month - total - manual on_breach: type: string enum: - block - warn limit_usd: type: string description: >- Display value. Decimal string, up to 9 fractional digits, trailing zeros trimmed, never exponent notation. Use limit_nano_usd for arithmetic. limit_nano_usd: type: - integer - 'null' description: >- Canonical integer amount, nano-USD. Null past the safe integer range, where limit_usd still reads. spent_usd: type: - string - 'null' description: >- Display value, null when spend_available is false. Decimal string, up to 9 fractional digits, trailing zeros trimmed, never exponent notation. Use spent_nano_usd for arithmetic. spent_nano_usd: type: - integer - 'null' description: >- Canonical integer spend, nano-USD. Null when spend is unavailable. Derived from the same integer as spent_usd, so the pair always agrees. timezone: type: - string - 'null' provider_key: type: - string - 'null' external_id: type: - string - 'null' metadata: type: object additionalProperties: type: string current_period_started_at: type: string description: >- Start of the period `spent_usd` covers, computed at read time. For an anchored budget this is its own cycle's start, not the calendar period's. resets_at: type: string description: >- When the current period gives way to the next. Far-future for total and manual windows, which do not roll on their own. cycle_anchor_at: type: - string - 'null' description: >- The instant this budget's cycle is phased to. Null means no anchor: a calendar-aligned cyclic window, or one of the two windows that do not cycle (total, manual). last_reset_at: type: - string - 'null' archived_at: type: - string - 'null' created_at: type: string member_count: type: integer end_users_seen: type: integer end_users_over: type: integer scope_reach: type: string enum: - reachable - unreachable description: >- Whether any active key in the organization can produce traffic this budget matches. `unreachable` means it will never accrue and never block as configured: scope a key to its target, or move the budget where the keys already run. This is the only field that tells a budget nothing can reach apart from one that simply has not been breached. required: - id - organization_id - scope_type - scope_id - name - description - window - on_breach - limit_usd - limit_nano_usd - spent_usd - spent_nano_usd - timezone - provider_key - external_id - metadata - current_period_started_at - resets_at - cycle_anchor_at - last_reset_at - archived_at - created_at required: - budget '400': description: Validation error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '403': description: Forbidden content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '409': description: Conflict content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string meta: type: object additionalProperties: {} trace_id: type: string span_id: type: string required: - type - code - message required: - error security: - project_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI. ````