--- title: List AI Gateway budgets description: List spend budgets for the organization, including active-window spend and effective capacity. breadcrumbs: Docs > API > List AI Gateway budgets --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List AI Gateway budgets ## 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 | GET https://api.datadoghq.com/api/v2/budgets | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/budgets | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/budgets | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/budgets | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/budgets | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/budgets | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/budgets | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/budgets | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/budgets | ### Overview List spend budgets for the organization, including active-window spend and effective capacity. This endpoint requires the `ai_gateway_config_read` permission. OAuth apps require the `ai_gateway_config_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#ai-gateway) to access this endpoint. ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing AI Gateway budgets. | Parent field | Field | Type | Description | | -------------------- | ----------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | data [*required*] | [object] | | | data | attributes [*required*] | object | Budget configuration including spend and capacity for the active accounting window. | | attributes | capacity_microcents [*required*] | int64 | Budget capacity in microcents. | | attributes | created_at [*required*] | date-time | Time when the resource was created. | | attributes | created_by [*required*] | string | Identifier of the principal that created the resource. | | attributes | current_period_capacity_microcents [*required*] | int64 | Capacity enforced for the active window, in microcents. | | attributes | current_spend_microcents [*required*] | int64 | Spend currently counted against the active window, in microcents. | | attributes | enabled [*required*] | boolean | Whether the resource is enabled. | | attributes | enforcement [*required*] | enum | Action taken when spend exceeds the budget. Allowed enum values: `BLOCK`, `NOTIFY`. | | attributes | monitor_id [*required*] | int64 | Datadog monitor ID provisioned for this budget. Null when monitor provisioning was skipped or failed. | | attributes | name [*required*] | string | Human-readable resource name. | | attributes | scope_restricted [*required*] | boolean | Whether provider or model scope metadata was withheld. Omit unchanged scope fields on an unrelated update to preserve their saved values. | | attributes | selector | [object] | Dimension rules for a template budget. A nonempty selector creates independent counters for matched instances. Omit or pass an empty selector for a legacy fixed-scope budget. | | selector | dim [*required*] | string | Dimension to match: user_id, team_id, model, provider, or tag:. Reserved metadata tag keys are rejected. | | selector | per_value [*required*] | boolean | Separate counters by the matched value when true. Otherwise, pool spend within the other separated dimensions. Default: `false`. | | selector | values | [string] | Allowed dimension values. Omit to match any value, including an absent dimension. An explicit list must contain at least one value. | | attributes | tags [*required*] | object | Request tags that must match for the budget to apply. | | additionalProperties | | string | | | attributes | team_id | uuid | Optional Datadog Team scope. | | attributes | updated_at [*required*] | date-time | Time when the resource was last updated. | | attributes | user_id | uuid | User scope. Omitted when the budget is not user-scoped. | | attributes | warning_threshold [*required*] | double | Fraction of capacity at which to issue a warning. | | attributes | window_end [*required*] | date-time | End of the active accounting window. | | attributes | window_policy [*required*] | enum | UTC accounting period for a budget. Allowed enum values: `DAILY`, `WEEKLY`, `MONTHLY`. | | attributes | window_start [*required*] | date-time | Start of the active accounting window. | | data | id [*required*] | uuid | Resource identifier. | | data | type [*required*] | enum | AI Gateway budget resource type. Allowed enum values: `budgets`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "capacity_microcents": 100000000, "created_at": "2026-08-24T12:00:00Z", "created_by": "admin@example.com", "current_period_capacity_microcents": 120000000, "current_spend_microcents": 25000000, "enabled": true, "enforcement": "BLOCK", "monitor_id": 12345678, "name": "Coding agents", "scope_restricted": false, "selector": [ { "dim": "user_id", "per_value": true, "values": [ "11111111-1111-1111-1111-111111111111" ] } ], "tags": { "": "string" }, "team_id": "string", "updated_at": "2026-08-24T12:00:00Z", "user_id": "string", "warning_threshold": 0.9, "window_end": "2026-09-01T00:00:00Z", "window_policy": "MONTHLY", "window_start": "2026-08-01T00:00:00Z" }, "id": "11111111-1111-1111-1111-111111111111", "type": "budgets" } ] } ``` {% /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 # 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="" curl -X GET "https://api.${DD_SITE}/api/v2/budgets" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}