> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a budget > Updates mutable fields of a budget: limits, rate limit, activation, and expiration. The scope is immutable — to change a budget's target, delete and recreate it. Omitted fields keep their current values. ## OpenAPI ````yaml patch /v2/budgets/{budget_id} openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/budgets/{budget_id}: patch: tags: - Budgets summary: Update a budget description: >- Updates mutable fields of a budget: limits, rate limit, activation, and expiration. The scope is immutable — to change a budget's target, delete and recreate it. Omitted fields keep their current values. operationId: BudgetUpdate parameters: - name: budget_id in: path description: Budget id to update. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateBudgetRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UpdateBudgetResponse' components: schemas: UpdateBudgetRequest: type: object properties: limits: allOf: - $ref: '#/components/schemas/BudgetLimits' description: New limits. Omit to keep current. rate_limit: allOf: - $ref: '#/components/schemas/RateLimit' description: New rate limit. Omit to keep current. is_active: type: boolean description: New active state. Omit to keep current. expires_at: type: string description: |- New expiration. Omit to keep current. Set `clear_expires_at = true` to remove an existing expiration. format: date-time clear_expires_at: type: boolean description: Force-clear the expiration. Mutually exclusive with `expires_at`. UpdateBudgetResponse: type: object properties: budget: allOf: - $ref: '#/components/schemas/Budget' description: Updated budget. BudgetLimits: type: object properties: period: $ref: '#/components/schemas/BudgetPeriod' amount: type: number format: double token_limit: type: string description: |- BudgetLimits is the per-period spend and token ceiling. At least one of `amount`, `token_limit`, or RateLimit.requests_per_minute MUST be set on a Budget; that invariant is enforced by the handler. RateLimit: type: object properties: requests_per_minute: type: integer format: int32 description: |- RateLimit is the per-minute request ceiling. Enforced via atomic increment-first semantics in the enforcement middleware. Budget: type: object properties: budget_id: type: string workspace_id: type: string scope: $ref: '#/components/schemas/BudgetScope' limits: $ref: '#/components/schemas/BudgetLimits' rate_limit: $ref: '#/components/schemas/RateLimit' is_active: type: boolean expires_at: format: date-time type: string created_at: format: date-time type: string updated_at: format: date-time type: string description: |- Budget is the canonical record stored in MongoDB `budgets.entities`. It replaces the embedded `constraints.budget` on api-keys and the legacy CONTACT-only `budgets.configs` collection (see ADR 0007). BudgetPeriod: type: string enum: - BUDGET_PERIOD_UNSPECIFIED - BUDGET_PERIOD_DAILY - BUDGET_PERIOD_WEEKLY - BUDGET_PERIOD_MONTHLY - BUDGET_PERIOD_YEARLY - BUDGET_PERIOD_ONE_TIME BudgetScope: type: object properties: workspace: $ref: '#/components/schemas/WorkspaceBudgetScope' project: $ref: '#/components/schemas/ProjectBudgetScope' identity: $ref: '#/components/schemas/IdentityBudgetScope' api_key: $ref: '#/components/schemas/ApiKeyBudgetScope' provider: $ref: '#/components/schemas/ProviderBudgetScope' model: $ref: '#/components/schemas/ModelBudgetScope' description: |- BudgetScope is a closed oneof. Exactly one variant must be set. The six variants are ordered by enforcement precedence (most specific to most general) and mirror the BudgetScopeKind filter enum. WorkspaceBudgetScope: type: object properties: {} description: Workspace-wide ceiling. The implicit target is the caller's workspace. ProjectBudgetScope: type: object properties: project_id: type: string description: Per-project cap. IdentityBudgetScope: type: object properties: identity_external_id: type: string description: |- Per-identity cap. Keyed by the contact's external_id (not the internal Mongo `_id`) so the scope is stable across imports. ApiKeyBudgetScope: type: object properties: api_key_id: type: string description: |- Per-api-key cap. Replaces the legacy embedded `constraints.budget` on auth.apiKeys. ProviderBudgetScope: type: object properties: provider: type: string description: |- Per-provider cap. The value is the provider enum string (e.g. "openai", "anthropic") drawn from ModelIntegrationIdentifier. ModelBudgetScope: type: object properties: model_id: type: string description: |- Per-model cap. The value is the provider-issued literal model_id (e.g. "gpt-4o") — NOT the Mongo `_id` of the model master-data document — so the scope is stable across workspaces. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````