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

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

# Reset a budget instance's spend

## 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/reset     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/budgets/{id}/instances/reset |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/budgets/{id}/instances/reset |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/budgets/{id}/instances/reset      |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/budgets/{id}/instances/reset |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/budgets/{id}/instances/reset |
| uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/budgets/{id}/instances/reset |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/budgets/{id}/instances/reset      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/budgets/{id}/instances/reset  |

### Overview

Reset active-period spend for one instance of a template budget, identified by its instance_key. The reset 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 reset one budget instance's active-period spend.                            |
| data         | attributes [*required*]   | object | Attributes used to reset one budget instance's active-period spend.                      |
| attributes   | instance_key [*required*] | string | Counter key of the instance to reset, as returned by the list budget instances endpoint. |
| attributes   | reason                    | string | Optional reason recorded with the spend reset.                                           |
| data         | type [*required*]         | enum   | Budget instance counter resource type. Allowed enum values: `budget-instances`.          |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "attributes": {
      "instance_key": "v1|7:user_id=36:22222222-2222-2222-2222-222222222222",
      "reason": "Credit approved after incorrect usage attribution"
    },
    "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/reset" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "instance_key": "v1|7:user_id=36:22222222-2222-2222-2222-222222222222",
      "reason": "Credit approved after incorrect usage attribution"
    },
    "type": "budget-instances"
  }
}
EOF
```
{% /tab %}
{% /tabs %}