---
title: "Reset budget consumption"
method: POST
path: "/v2/budgets/{budget_id}/reset-consumption"
tags: ["Budgets"]
---

# Reset budget consumption

`POST /v2/budgets/{budget_id}/reset-consumption`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/budgets/{budget_id}/reset-consumption`
- Auth: HTTP bearer

Clears the current-period cost, token, and request counters for the budget. The budget record itself is preserved. Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

## Path parameters

- `budget_id` string, required

## Request body

- ResetBudgetConsumptionRequest

## Response `200`

OK

- ResetBudgetConsumptionResponse
  - `budget` BudgetRestResponse: Budget defines limits and matching rules used to govern consumption.
    - `budgetId` string, required
    - `scope` BudgetScopeRestResponse: Closed oneof of workspace, project, identity, api_key, provider, or model. Exactly one variant must be set.
      - `workspace` WorkspaceBudgetScope: Workspace-wide ceiling. The implicit target is the caller's workspace.
      - `project` ProjectBudgetScopeRestResponse: Per-project cap.
        - `projectId` string
      - `identity` IdentityBudgetScopeRestResponse: Per-identity cap. Keyed by the contact's external identifier so the scope is stable across imports.
        - `identityExternalId` string
      - `apiKey` ApiKeyBudgetScopeRestResponse: Per-api-key cap. Replaces the legacy embedded `constraints.budget` associated with an API key.
        - `apiKeyId` string
      - `provider` ProviderBudgetScope: Per-provider cap. The value is the provider identifier, for example "openai" or "anthropic".
        - `provider` string
      - `model` ModelBudgetScopeRestResponse: Per-model cap. The value is the FULL model reference as callers send it ("openai/gpt-4o", or "workspaceKey@openai/gpt-4o" for private models).
        - `modelId` string, required
    - `match` BudgetMatch: CEL expression that decides whether a budget applies to a request. Available variables: `model`, `provider`, `model_id`, `api_key`, `identity`, `project`, `metadata` (map), `headers` (map, lowercase keys). Required unless the budget is created from a `scope`, and rejected on update when left empty. A workspace-wide budget stores an empty expression, which matches every request in the workspace. Expressions are syntax-validated at write time.
      - `cel` string
    - `limits` BudgetLimitsRestResponse, required: 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.
      - `period` 'BUDGET_PERIOD_DAILY' | 'BUDGET_PERIOD_WEEKLY' | 'BUDGET_PERIOD_MONTHLY' | 'BUDGET_PERIOD_YEARLY' | 'BUDGET_PERIOD_ONE_TIME'
      - `amount` number, double
      - `tokenLimit` number, double: Token ceiling for the budget period. Token counts are whole numbers and stored as integers.
    - `rateLimit` RateLimitRestResponse: Per-minute request ceiling applied to the requests this budget matches.
      - `requestsPerMinute` integer
    - `isActive` boolean
    - `expiresAt` string, date-time
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `usage` BudgetUsage: BudgetUsage is the latest available current-period consumption used for budget enforcement, not an exact billing ledger. Each dimension is the consumed side of the matching limit dimension: `amount` is the accumulated cost in USD (vs limits.amount), `tokens` is the accumulated token count (vs limits.token_limit), and `requests` is the count in the rolling 60-second window (vs rate_limit.requests_per_minute). All three are explicit-presence so the triple is always emitted in full, zeros included — a never-spent budget serializes {amount:0, tokens:0, requests:0} rather than dropping its zero dimensions.
      - `amount` number, double
      - `tokens` number, double: Tokens accumulated in the current period.
      - `requests` integer
    - `alerts` BudgetAlertRestResponse[]: Threshold notifications. Absent when the budget has none.
      - `id` string: Assigned by ORQ. Supply an existing id to edit that alert in place.
      - `thresholdPercent` integer, required: Percentage of the dimension's limit at which the alert fires, 1–100.
      - `notifierIds` string[], required: Must be workspace-scoped; project-scoped notifiers are rejected.
      - `dimension` 'BUDGET_ALERT_DIMENSION_COST' | 'BUDGET_ALERT_DIMENSION_TOKENS'

## Other responses

- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 3 info
  - added the non-success response with the status `401`
  - removed the `BUDGET_ALERT_DIMENSION_UNSPECIFIED` enum value from the `budget/allOf[#/components/schemas/BudgetRestResponse]/alerts/items/dimension` response property for the response status `200`
  - removed the `BUDGET_PERIOD_UNSPECIFIED` enum value from the `budget/allOf[#/components/schemas/BudgetRestResponse]/limits/period` response property for the response status `200`
- **2026-10-23** `732aed62833a`: 2 warning, 1 info
  - added the new `BUDGET_ALERT_DIMENSION_UNSPECIFIED` enum value to the `budget/allOf[#/components/schemas/BudgetRestResponse]/alerts/items/dimension` response property for the response status `200`
  - added the new `BUDGET_PERIOD_UNSPECIFIED` enum value to the `budget/allOf[#/components/schemas/BudgetRestResponse]/limits/period` response property for the response status `200`
  - removed the non-success response with the status `401`
- **2026-10-22** `4f826b2c3a0e`: 3 info
  - added the non-success response with the status `401`
  - removed the `BUDGET_ALERT_DIMENSION_UNSPECIFIED` enum value from the `budget/allOf[#/components/schemas/BudgetRestResponse]/alerts/items/dimension` response property for the response status `200`
  - removed the `BUDGET_PERIOD_UNSPECIFIED` enum value from the `budget/allOf[#/components/schemas/BudgetRestResponse]/limits/period` response property for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/budgets/:budget_id/reset-consumption/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)