---
title: "Override a budget instance's capacity"
method: POST
path: "/api/v2/budgets/{id}/instances/capacity"
tags: ["AI Gateway"]
---

# Override a budget instance's capacity

`POST /api/v2/budgets/{id}/instances/capacity`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/budgets/{id}/instances/capacity`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `ai_gateway_config_write`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/budgets/:id/instances/capacity/post.ts> (a function with typed inputs; its response is checked against the schema)

Override active-period capacity for one instance of a template budget, identified by its instance_key. Other instances and the budget's default capacity are unchanged. The override is retained in the budget adjustment audit history. Returns 404 when the instance has no counter in the active period. Not supported for legacy fixed-scope budgets.

## Path parameters

- `id` string, uuid, required

## Request body

- AiGatewayBudgetInstanceCapacityOverrideRequest: Request to override one budget instance's active-period capacity.
  - `data` AiGatewayBudgetInstanceCapacityOverrideData, required: Data used to override one budget instance's active-period capacity.
    - `attributes` AiGatewayBudgetInstanceCapacityOverrideAttributes, required: Attributes used to override one budget instance's active-period capacity.
      - `capacity_microcents` integer, required: New capacity for this instance in the active accounting period, in microcents.
      - `instance_key` string, required: Counter key of the instance to override, as returned by the list budget instances endpoint.
      - `reason` string: Optional reason recorded with the capacity override.
    - `type` 'budget-instances', required: Budget instance counter resource type.

## Response `200`

OK

- AiGatewayBudgetInstanceResponse: Response containing one budget instance counter.
  - `data` AiGatewayBudgetInstanceResource, required: One budget instance counter.
    - `attributes` AiGatewayBudgetInstanceAttributes, required: One budget instance counter.
      - `budget_id` string, uuid, required: Budget identifier.
      - `effective_capacity_microcents` integer, required: Capacity enforced for this instance, in microcents.
      - `instance_key` string, required: Opaque canonical counter key. Empty for legacy pooled counters.
      - `modified_at` string, date-time, required: Time the instance counter was last modified.
      - `spend_microcents` integer, required: Spend counted against this instance, in microcents.
      - `split_dims` object, required: Dimension values decoded from instance_key. User and Team values are raw UUIDs.
      - `window_start` string, date-time, required: Start of the accounting window.
    - `id` string, required: Resource identifier.
    - `type` 'budget-instances', required: Budget instance counter resource type.

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)