---
title: Override a budget instance's capacity
description: Override active-period capacity for one instance of a template budget, identified by its instance_key.
breadcrumbs: Docs > API > Override a budget instance's capacity
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Override a budget instance's capacity

## v2 (latest)

{% alert level="warning" %}
**Note**: This endpoint is in Preview and is subject to change.
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md).
{% /alert %}

| Datadog site      | API endpoint                                                              |
| ----------------- | ------------------------------------------------------------------------- |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/budgets/{id}/instances/capacity     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/budgets/{id}/instances/capacity |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/budgets/{id}/instances/capacity |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/budgets/{id}/instances/capacity      |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/budgets/{id}/instances/capacity |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/budgets/{id}/instances/capacity |
| uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/budgets/{id}/instances/capacity |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/budgets/{id}/instances/capacity      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/budgets/{id}/instances/capacity  |

### Overview

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.

This endpoint requires the `ai_gateway_config_write` permission.

OAuth apps require the `ai_gateway_config_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#ai-gateway) to access this endpoint.

### Arguments

#### Path Parameters

| Field           | Type   | Description  |
| --------------- | ------ | ------------ |
| id [*required*] | string | Budget UUID. |

### Request

#### Body Data (required)

{% tabs %}
{% tab label="Model" %}
| Parent field | Field                            | Type   | Description                                                                                 |
| ------------ | -------------------------------- | ------ | ------------------------------------------------------------------------------------------- |
|              | data [*required*]                | object | Data used to override one budget instance's active-period capacity.                         |
| data         | attributes [*required*]          | object | Attributes used to override one budget instance's active-period capacity.                   |
| attributes   | capacity_microcents [*required*] | int64  | New capacity for this instance in the active accounting period, in microcents.              |
| attributes   | instance_key [*required*]        | string | Counter key of the instance to override, as returned by the list budget instances endpoint. |
| attributes   | reason                           | string | Optional reason recorded with the capacity override.                                        |
| data         | type [*required*]                | enum   | Budget instance counter resource type. Allowed enum values: `budget-instances`.             |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "attributes": {
      "capacity_microcents": 250000000,
      "instance_key": "v1|7:user_id=36:22222222-2222-2222-2222-222222222222",
      "reason": "Temporary increase for a launch week"
    },
    "type": "budget-instances"
  }
}
```
{% /tab %}
{% /tabs %}

### Response

{% tabs %}
{% tab label="200" %}
OK

{% tabs %}
{% tab label="Model" %}
Response containing one budget instance counter.

| Parent field         | Field                                      | Type      | Description                                                                     |
| -------------------- | ------------------------------------------ | --------- | ------------------------------------------------------------------------------- |
|                      | data [*required*]                          | object    | One budget instance counter.                                                    |
| data                 | attributes [*required*]                    | object    | One budget instance counter.                                                    |
| attributes           | budget_id [*required*]                     | uuid      | Budget identifier.                                                              |
| attributes           | effective_capacity_microcents [*required*] | int64     | Capacity enforced for this instance, in microcents.                             |
| attributes           | instance_key [*required*]                  | string    | Opaque canonical counter key. Empty for legacy pooled counters.                 |
| attributes           | modified_at [*required*]                   | date-time | Time the instance counter was last modified.                                    |
| attributes           | spend_microcents [*required*]              | int64     | Spend counted against this instance, in microcents.                             |
| attributes           | split_dims [*required*]                    | object    | Dimension values decoded from instance_key. User and Team values are raw UUIDs. |
| additionalProperties | <any-key>                                  | string    |                                                                                 |
| attributes           | window_start [*required*]                  | date-time | Start of the accounting window.                                                 |
| data                 | id [*required*]                            | string    | Resource identifier.                                                            |
| data                 | type [*required*]                          | enum      | Budget instance counter resource type. Allowed enum values: `budget-instances`. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "attributes": {
      "budget_id": "11111111-1111-1111-1111-111111111111",
      "effective_capacity_microcents": 100000000,
      "instance_key": "",
      "modified_at": "2026-10-05T12:00:00Z",
      "spend_microcents": 25000000,
      "split_dims": {
        "<any-key>": "string"
      },
      "window_start": "2026-10-01T00:00:00Z"
    },
    "id": "11111111-1111-1111-1111-111111111111|2026-10-01T00:00:00Z|",
    "type": "budget-instances"
  }
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Bad Request

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="404" %}
Not Found

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="429" %}
Too many requests

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

### Code Example

{% tabs %}
{% tab label="Curl" %}
```bash
# Path parameters
export id="11111111-1111-1111-1111-111111111111"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/budgets/${id}/instances/capacity" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "capacity_microcents": 250000000,
      "instance_key": "v1|7:user_id=36:22222222-2222-2222-2222-222222222222",
      "reason": "Temporary increase for a launch week"
    },
    "type": "budget-instances"
  }
}
EOF
```
{% /tab %}
{% /tabs %}