DAdatadog
AI Gateway

List AI Gateway budget instance dimension values

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.

get/api/v2/budgets/{id}/instances/dimensions

Request

Path parameters

idstring uuid required

Budget UUID.

Query parameters

windowstring date-time

RFC3339 timestamp inside the desired accounting window. Omit to use the current window.

split_dimstring[]

Keep only instance counters whose split dimension equals a value, written as <dim>=<value>, such as split_dim=user_id=<uuid>&split_dim=tag:env=prod. Dimensions use the split_dims names user_id, team_id, model, provider, and tag:<key>. 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.

dimstring[]

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.

querystring

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.

valuestring[]

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.

limitinteger

Maximum number of values to return per dimension.

Response

OK

Example response

{
  "data": [
    {
      "attributes": {
        "budget_id": "11111111-1111-1111-1111-111111111111",
        "dim": "tag:env",
        "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"
    }
  ]
}

Changes

Changes to this operation have not been checked yet.