--- title: List AI Gateway budget instance dimension values description: Search the values that a template budget's split dimensions take across its instance counters in an accounting window. breadcrumbs: Docs > API > List AI Gateway budget instance dimension values --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List AI Gateway budget instance dimension values ## 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/{id}/instances/dimensions | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/budgets/{id}/instances/dimensions | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/budgets/{id}/instances/dimensions | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/budgets/{id}/instances/dimensions | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/budgets/{id}/instances/dimensions | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/budgets/{id}/instances/dimensions | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/budgets/{id}/instances/dimensions | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/budgets/{id}/instances/dimensions | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/budgets/{id}/instances/dimensions | ### Overview Search the values that a template budget's split dimensions take across its instance counters in an accounting window. Each dimension returns its top values by spend, with counter counts. Use query or value to narrow results and limit to cap them. The truncated field reports whether more values matched. Each dimension's values are counted under the other dimensions' split_dim filters, so a dimension's own filter does not hide its alternatives. Legacy fixed-scope budgets return an empty list. 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. ### Arguments #### Path Parameters | Field | Type | Description | | --------------- | ------ | ------------ | | id [*required*] | string | Budget UUID. | #### Query Strings | Field | Type | Description | | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | window | string | RFC3339 timestamp inside the desired accounting window. Omit to use the current window. | | split_dim | array | Keep only instance counters whose split dimension equals a value, written as `=`, such as `split_dim=user_id=&split_dim=tag:env=prod`. Dimensions use the `split_dims` names `user_id`, `team_id`, `model`, `provider`, and `tag:`. Repeat the parameter to filter on several dimensions; a counter must match all of them. Each dimension may appear once and must be a per-value dimension of the budget. | | dim | array | Return only these split dimensions, such as `dim=user_id`. Repeat the parameter for several dimensions. Omit it to return every split dimension of the budget. | | query | string | Keep only values that contain this text, case-insensitively. It matches raw values, so User and Team values match their UUIDs; search their names elsewhere and pass the IDs as `value`. | | value | array | Keep only these values. Repeat the parameter to check several candidates, such as User IDs found by name, and learn which of them have instance counters. | | limit | integer | Maximum number of values to return per dimension. Default: `50`. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing values of budget split dimensions. | Parent field | Field | Type | Description | | ------------ | ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | | | data | attributes [*required*] | object | Values of one budget split dimension. | | attributes | budget_id [*required*] | uuid | Budget identifier. | | attributes | dim [*required*] | string | Split dimension name, as used in `split_dims` and the `split_dim` filter. | | attributes | restricted_details [*required*] | boolean | Whether identifying instance details were withheld. Aggregate totals still include restricted instances. | | attributes | truncated [*required*] | boolean | Whether more values matched than were returned. Narrow the results with `query` or `value` to see them. | | attributes | values [*required*] | [object] | Values of this dimension across matching instance counters, highest spend first and at most `limit` of them. Values are counted under every `split_dim` filter except the one for this dimension. | | values | instance_count [*required*] | int64 | Number of instance counters carrying this value. | | values | spend_microcents [*required*] | int64 | Spend summed across those instance counters, in microcents. | | values | value [*required*] | string | Raw dimension value. User and Team values are UUIDs. A counter with no value for the dimension carries the null character (U+0000). | | attributes | window_start [*required*] | date-time | Start of the accounting window. | | data | id [*required*] | string | Resource identifier. | | data | type [*required*] | enum | Budget split dimension values resource type. Allowed enum values: `budget-instance-dimensions`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "budget_id": "11111111-1111-1111-1111-111111111111", "dim": "tag:env", "restricted_details": false, "truncated": false, "values": [ { "instance_count": 2, "spend_microcents": 50000000, "value": "prod" } ], "window_start": "2026-10-01T00:00:00Z" }, "id": "11111111-1111-1111-1111-111111111111|2026-10-01T00:00:00Z|tag:env", "type": "budget-instance-dimensions" } ] } ``` {% /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="" curl -X GET "https://api.${DD_SITE}/api/v2/budgets/${id}/instances/dimensions" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}