AI Gateway

List AI Gateway rate limit counters

Changed on

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.

get/api/v2/rate-limits/{id}/instances

Request

  • Base URL
    https://api.datadoghq.com
  • Auth
    • API key in header DD-API-KEY and API key in header DD-APPLICATION-KEY
    • or OAuth 2
      Authorization code/oauth2/v1/authorize
      Token URL/oauth2/v1/token
      Scopesai_gateway_config_read

Path parameters

idstring uuid required

Rate limit UUID.

Query parameters

split_dimstring[]

Keep only counters whose split dimension equals a value, written as <dim>=<value>, such as split_dim=user_id=<uuid>&split_dim=model=gpt-4o. 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 rate limit.

sort'utilization_desc' | 'last_seen_desc' | 'key_asc'

Sort order for rate limit counters.

Example:utilization_desc
limitinteger

Maximum number of rate limit counters to return.

offsetinteger

Number of rate limit counters to skip.

Response

OK

Example response

{
  "data": [
    {
      "attributes": {
        "cost_microcents": 25000000,
        "cost_microcents_per_minute": 100000000,
        "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",
        "output_tokens": 4000,
        "output_tokens_per_minute": 20000,
        "rate_limit_id": "33333333-3333-3333-3333-333333333333",
        "requests": 42,
        "requests_per_minute": 60,
        "split_dims": {
          "user_id": "11111111-1111-1111-1111-111111111111"
        },
        "usage_known": true,
        "utilization": 0.7
      },
      "id": "33333333-3333-3333-3333-333333333333|v1|7:user_id=36:11111111-1111-1111-1111-111111111111",
      "type": "rate-limit-instances"
    }
  ]
}

Changes

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      endpoint added