---
title: Get AI Gateway rate limit usage
description: Get live usage for the organization's rate limits.
breadcrumbs: Docs > API > Get AI Gateway rate limit usage
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Get AI Gateway rate limit usage

## 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/usage     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/rate-limits/usage |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/rate-limits/usage |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/rate-limits/usage      |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/rate-limits/usage |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/rate-limits/usage |
| uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/rate-limits/usage |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/rate-limits/usage      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/rate-limits/usage  |

### Overview

Get live usage for the organization's rate limits. Returns requests and tokens counted in the rolling one-minute window and requests limited in the last 15 minutes for each enabled rate limit, plus `untracked` (traffic no enforced rate limit covers) and `total` (all gateway traffic).

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.

### Response

{% tabs %}
{% tab label="200" %}
OK

{% tabs %}
{% tab label="Model" %}
Response containing live usage for the organization's AI Gateway rate limits.

| Parent field | Field                             | Type     | Description                                                                                                 |
| ------------ | --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
|              | data [*required*]                 | [object] |                                                                                                             |
| data         | attributes [*required*]           | object   | Live consumption of one AI Gateway rate limit.                                                              |
| attributes   | input_tokens [*required*]         | int64    | Input tokens counted in the rolling one-minute window.                                                      |
| attributes   | limited_requests [*required*]     | int64    | Requests this rate limit rejected in the last 15 minutes. Applies when mode is ENFORCE.                     |
| attributes   | output_tokens [*required*]        | int64    | Output tokens counted in the rolling one-minute window.                                                     |
| attributes   | requests [*required*]             | int64    | Requests counted in the rolling one-minute window.                                                          |
| attributes   | would_limit_requests [*required*] | int64    | Requests this rate limit would have rejected in the last 15 minutes. Applies when mode is ALERT.            |
| data         | id [*required*]                   | string   | Rate limit UUID, `untracked` for traffic no enforced rate limit covers, or `total` for all gateway traffic. |
| data         | type [*required*]                 | enum     | AI Gateway rate limit usage resource type. Allowed enum values: `rate-limit-usage`.                         |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": [
    {
      "attributes": {
        "input_tokens": 45000,
        "limited_requests": 3,
        "output_tokens": 12000,
        "requests": 120,
        "would_limit_requests": 0
      },
      "id": "33333333-3333-3333-3333-333333333333",
      "type": "rate-limit-usage"
    }
  ]
}
```
{% /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
# 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="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/rate-limits/usage" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
```
{% /tab %}
{% /tabs %}