DAdatadog
AI Gateway

List AI Gateway budget instances

List instance counters for an accounting window. Legacy fixed-scope budgets return one pooled row with an empty instance_key. Omit window to use the current window. Use split_dim to keep only counters that match every given dimension value.

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

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.

sort'spend_desc' | 'spend_asc' | 'key_asc'

Sort order for budget instance counters.

Example:spend_desc
limitinteger

Maximum number of budget instance counters to return.

offsetinteger

Number of budget instance counters to skip.

Response

OK

Example response

{
  "data": [
    {
      "attributes": {
        "budget_id": "11111111-1111-1111-1111-111111111111",
        "effective_capacity_microcents": 100000000,
        "modified_at": "2026-10-05T12:00:00Z",
        "spend_microcents": 25000000,
        "split_dims": {},
        "window_start": "2026-10-01T00:00:00Z"
      },
      "id": "11111111-1111-1111-1111-111111111111|2026-10-01T00:00:00Z|",
      "type": "budget-instances"
    }
  ]
}

Changes

Changes to this operation have not been checked yet.