---
title: "List AI Gateway budget instance dimension values"
method: GET
path: "/api/v2/budgets/{id}/instances/dimensions"
tags: ["AI Gateway"]
---

# List AI Gateway budget instance dimension values

`GET /api/v2/budgets/{id}/instances/dimensions`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/budgets/{id}/instances/dimensions`
- 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_read`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/budgets/:id/instances/dimensions/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `window` string, date-time
- `split_dim` string[]
- `dim` string[]
- `query` string
- `value` string[]
- `limit` integer

## Response `200`

OK

- AiGatewayBudgetInstanceDimensionListResponse: Response containing values of budget split dimensions.
  - `data` AiGatewayBudgetInstanceDimensionResource[], required
    - `attributes` AiGatewayBudgetInstanceDimensionAttributes, required: Values of one budget split dimension.
      - `budget_id` string, uuid, required: Budget identifier.
      - `dim` string, required: Split dimension name, as used in `split_dims` and the `split_dim` filter.
      - `restricted_details` boolean, required: Whether identifying instance details were withheld. Aggregate totals still include restricted instances.
      - `truncated` boolean, required: Whether more values matched than were returned. Narrow the results with `query` or `value` to see them.
      - `values` AiGatewayBudgetInstanceDimensionValue[], required: 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.
        - `instance_count` integer, required: Number of instance counters carrying this value.
        - `spend_microcents` integer, required: Spend summed across those instance counters, in microcents.
        - `value` string, required: Raw dimension value. User and Team values are UUIDs. A counter with no value for the dimension carries the null character (U+0000).
      - `window_start` string, date-time, required: Start of the accounting window.
    - `id` string, required: Resource identifier.
    - `type` 'budget-instance-dimensions', required: Budget split dimension values 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)