---
title: "List AI Gateway rate limit counters"
method: GET
path: "/api/v2/rate-limits/{id}/instances"
tags: ["AI Gateway"]
---

# List AI Gateway rate limit counters

`GET /api/v2/rate-limits/{id}/instances`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/rate-limits/{id}/instances`
- 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`

List the hot counters of a template rate limit, one per matched user, Team, or value, with their live usage. Only counters at 80% or more of a limit, or that limited or would have limited a request, in the last hour are listed. A counter appears within a few minutes of becoming hot. Usage is read for at most 200 counters per request; past that, rows carry usage_known false. Counters for a provider or model the caller can't see are left out, and when the caller can't see the template's selector, the list is empty. A rate limit with one shared allowance, including one whose selector has no per_value entry, returns an empty list. Returns 503 when counter usage can't be read.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `split_dim` string[]
- `sort` 'utilization_desc' | 'last_seen_desc' | 'key_asc': Sort order for rate limit counters.
- `limit` integer
- `offset` integer

## Response `200`

OK

- AiGatewayRateLimitInstanceListResponse: Response containing counters of a template rate limit.
  - `data` AiGatewayRateLimitInstanceResource[], required
    - `attributes` AiGatewayRateLimitInstanceAttributes, required: One counter of a template rate limit and its live usage.
      - `cost_microcents` integer: Priced spend, in microcents, counted in the rolling one-minute window. 0 when the rate limit doesn't limit cost.
      - `cost_microcents_per_minute` integer, nullable: The rate limit's per-counter spend limit, in microcents. Null when it doesn't limit cost.
      - `first_seen` string, date-time, required: When the gateway first recorded a request for this counter.
      - `input_tokens` integer, required: Input tokens counted in the rolling one-minute window.
      - `input_tokens_per_minute` integer, nullable: The rate limit's per-counter input token limit. Null when it doesn't limit input tokens.
      - `instance_key` string, required: Opaque canonical key identifying the counter.
      - `last_seen` string, date-time, required: When the gateway last saw this counter hot, that is near or at a limit or limiting; up to a few minutes behind live traffic.
      - `limited_requests` integer, required: Requests this counter rejected in the last 15 minutes (ENFORCE).
      - `output_tokens` integer, required: Output tokens counted in the rolling one-minute window.
      - `output_tokens_per_minute` integer, nullable: The rate limit's per-counter output token limit. Null when it doesn't limit output tokens.
      - `rate_limit_id` string, uuid, required: Rate limit UUID.
      - `requests` integer, required: Requests counted in the rolling one-minute window.
      - `requests_per_minute` integer, nullable: The rate limit's per-counter request limit. Null when it doesn't limit requests.
      - `split_dims` object, required: The counter's value for each per-value dimension. user_id and team_id values are raw UUIDs.
      - `usage_known` boolean, required: False when this counter's usage wasn't read because the request already read the most counters it may. Its usage then reads as zero.
      - `utilization` number, double, required: The fullest of the rate limit's limits in the rolling window, as a fraction. 1 or more means the counter is at its limit.
      - `would_limit_requests` integer, required: Requests this counter would have rejected in the last 15 minutes (ALERT).
    - `id` string, required: Counter ID, the rate limit UUID and instance key joined by `|`.
    - `type` 'rate-limit-instances', required: AI Gateway rate limit counter resource type.

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `429`: Too many requests

## Changes

- **2026-11-13** `14d85160bfa9`: 2 info
  - added the optional property `data/items/attributes/cost_microcents` to the response with the `200` status
  - added the optional property `data/items/attributes/cost_microcents_per_minute` to the response with the `200` status
- **2026-11-13** `6d6d61de83e2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/changes/api/v2/rate-limits/:id/instances/get.md)

---

[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/14d85160bfa9?raw)
