--- title: List AI Gateway rate limit counters description: List the counters of a template rate limit, one per matched user, Team, or value, with their live usage. breadcrumbs: Docs > API > List AI Gateway rate limit counters --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List AI Gateway rate limit counters ## 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/rate-limits/{id}/instances | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/rate-limits/{id}/instances | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/rate-limits/{id}/instances | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/rate-limits/{id}/instances | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/rate-limits/{id}/instances | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/rate-limits/{id}/instances | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/rate-limits/{id}/instances | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/rate-limits/{id}/instances | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/rate-limits/{id}/instances | ### Overview List the counters of a template rate limit, one per matched user, Team, or value, with their live usage. Counters appear within a few minutes of their first request and are dropped after 30 days without one. Usage is read for counters seen in the last 20 minutes, at most 200 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. 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 | Rate limit UUID. | #### Query Strings | Field | Type | Description | | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | split_dim | array | Keep only counters whose split dimension equals a value, written as `=`, such as `split_dim=user_id=&split_dim=model=gpt-4o`. 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 rate limit. | | sort | enum | Sort order for rate limit counters. Allowed enum values: `utilization_desc`, `last_seen_desc`, `key_asc`. Default: `utilization_desc`. | | limit | integer | Maximum number of rate limit counters to return. Default: `50`. | | offset | integer | Number of rate limit counters to skip. Default: `0`. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing counters of a template rate limit. | Parent field | Field | Type | Description | | -------------------- | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ | | | data [*required*] | [object] | | | data | attributes [*required*] | object | One counter of a template rate limit and its live usage. | | attributes | first_seen [*required*] | date-time | When the gateway first recorded a request for this counter. | | attributes | input_tokens [*required*] | int64 | Input tokens counted in the rolling one-minute window. | | attributes | input_tokens_per_minute | int64 | The rate limit's per-counter input token limit. Null when it doesn't limit input tokens. | | attributes | instance_key [*required*] | string | Opaque canonical key identifying the counter. | | attributes | last_seen [*required*] | date-time | When the gateway last recorded a request for this counter; up to a few minutes behind live traffic. | | attributes | limited_requests [*required*] | int64 | Requests this counter rejected in the last 15 minutes (ENFORCE). | | attributes | output_tokens [*required*] | int64 | Output tokens counted in the rolling one-minute window. | | attributes | output_tokens_per_minute | int64 | The rate limit's per-counter output token limit. Null when it doesn't limit output tokens. | | attributes | rate_limit_id [*required*] | uuid | Rate limit UUID. | | attributes | requests [*required*] | int64 | Requests counted in the rolling one-minute window. | | attributes | requests_per_minute | int64 | The rate limit's per-counter request limit. Null when it doesn't limit requests. | | attributes | split_dims [*required*] | object | The counter's value for each per-value dimension. user_id and team_id values are raw UUIDs. | | additionalProperties | | string | | | attributes | usage_known [*required*] | boolean | 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. | | attributes | utilization [*required*] | double | 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. | | attributes | would_limit_requests [*required*] | int64 | Requests this counter would have rejected in the last 15 minutes (ALERT). | | data | id [*required*] | string | Counter ID, the rate limit UUID and instance key joined by `|`. | | data | type [*required*] | enum | AI Gateway rate limit counter resource type. Allowed enum values: `rate-limit-instances`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "first_seen": "2026-10-28T10:00:00Z", "input_tokens": 15000, "input_tokens_per_minute": 100000, "instance_key": "v1|7:user_id=36:11111111-1111-1111-1111-111111111111", "last_seen": "2026-10-28T10:05:00Z", "limited_requests": 0, "output_tokens": 4000, "output_tokens_per_minute": 20000, "rate_limit_id": "33333333-3333-3333-3333-333333333333", "requests": 42, "requests_per_minute": 60, "split_dims": { "": "string" }, "usage_known": true, "utilization": 0.7, "would_limit_requests": 0 }, "id": "33333333-3333-3333-3333-333333333333|v1|7:user_id=36:11111111-1111-1111-1111-111111111111", "type": "rate-limit-instances" } ] } ``` {% /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="33333333-3333-3333-3333-333333333333" # 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/rate-limits/${id}/instances" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}