--- title: Create an AI Gateway rate limit description: Create a rate limit. breadcrumbs: Docs > API > Create an AI Gateway rate limit --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Create an AI Gateway rate limit ## 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 | POST https://api.datadoghq.com/api/v2/rate-limits | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/rate-limits | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/rate-limits | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/rate-limits | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/rate-limits | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/rate-limits | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/rate-limits | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/rate-limits | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/rate-limits | ### Overview Create a rate limit. All requests matching its scope share one allowance, and every matching rate limit applies. Returns 409 when another active rate limit has the same user, Team, and tags, or when the organization already has the maximum number of rate limits. This endpoint requires the `ai_gateway_config_write` permission. OAuth apps require the `ai_gateway_config_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#ai-gateway) to access this endpoint. ### Request #### Body Data (required) {% tabs %} {% tab label="Model" %} | Parent field | Field | Type | Description | | -------------------- | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | Data used to create an AI Gateway rate limit. | | data | attributes [*required*] | object | Attributes used to create an AI Gateway rate limit. | | attributes | input_tokens_per_minute | int64 | Maximum input tokens per rolling minute. | | attributes | mode | enum | Action taken when request rate exceeds the limit. Allowed enum values: `ALERT`, `ENFORCE`. | | attributes | name [*required*] | string | Rate limit name. Must not be empty. | | attributes | output_tokens_per_minute | int64 | Maximum output tokens per rolling minute. | | attributes | requests_per_minute | int64 | Maximum requests per rolling minute. At least one of `requests_per_minute`, `input_tokens_per_minute`, and `output_tokens_per_minute` is required. | | attributes | tags | object | Optional scope tags, such as `provider`, `model`, `ml_app`, or custom dimensions. A request matches when it has all of these tags. The reserved metadata keys `name`, `budget_name`, and `span_filter` are rejected. | | additionalProperties | | string | | | attributes | team_id | uuid | Optional UUID. Count only requests attributed to this Datadog Team. | | attributes | user_id | uuid | Optional UUID. Count only this user's requests. | | data | type [*required*] | enum | AI Gateway rate limit resource type. Allowed enum values: `rate-limits`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "input_tokens_per_minute": "integer", "mode": "ALERT", "name": "Default rate limit", "output_tokens_per_minute": "integer", "requests_per_minute": 600, "tags": { "": "string" }, "team_id": "00000000-0000-4000-8000-000000000002", "user_id": "00000000-0000-4000-8000-000000000001" }, "type": "rate-limits" } } ``` {% /tab %} {% /tabs %} ### Response {% tabs %} {% tab label="201" %} Created {% tabs %} {% tab label="Model" %} Response containing one AI Gateway rate limit. | Parent field | Field | Type | Description | | -------------------- | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | AI Gateway rate limit resource. | | data | attributes [*required*] | object | Attributes of an AI Gateway rate limit. | | attributes | created_at [*required*] | date-time | Creation timestamp. | | attributes | created_by [*required*] | string | Email of the user who created this rate limit. | | attributes | enabled [*required*] | boolean | Whether this rate limit is active. | | attributes | input_tokens_per_minute | int64 | Maximum input tokens per rolling minute shared by all matching traffic. Null when this rule does not limit input tokens. | | attributes | mode [*required*] | enum | Action taken when request rate exceeds the limit. Allowed enum values: `ALERT`, `ENFORCE`. | | attributes | monitor_id | int64 | Datadog monitor that alerts on this rule. Null until one is provisioned. | | attributes | name [*required*] | string | Rate limit name. | | attributes | output_tokens_per_minute | int64 | Maximum output tokens per rolling minute shared by all matching traffic. Null when this rule does not limit output tokens. | | attributes | requests_per_minute | int64 | Maximum requests per rolling minute shared by all matching traffic. Null when this rule does not limit requests. | | attributes | revision [*required*] | int64 | Increases on every change to the definition. | | attributes | scope_restricted [*required*] | boolean | Whether provider or model scope metadata was withheld. Omit unchanged scope fields on an unrelated update to preserve their saved values. | | attributes | tags [*required*] | object | Optional scope tags, such as provider, model, ml_app, or custom dimensions. A request matches when it has all of these tags. | | additionalProperties | | string | | | attributes | team_id | uuid | Optional Team UUID. Count only requests attributed to this Datadog Team. | | attributes | updated_at [*required*] | date-time | Last modification timestamp. | | attributes | updated_by [*required*] | string | Email of the user who last modified this rate limit. | | attributes | user_id | uuid | Optional user UUID. Count only this user's requests. | | data | id [*required*] | uuid | Rate limit UUID. | | data | type [*required*] | enum | AI Gateway rate limit resource type. Allowed enum values: `rate-limits`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "created_at": "2026-09-01T00:00:00Z", "created_by": "user@example.com", "enabled": true, "input_tokens_per_minute": 500000, "mode": "ALERT", "monitor_id": 12345678, "name": "Default rate limit", "output_tokens_per_minute": 200000, "requests_per_minute": 1000, "revision": 1, "scope_restricted": false, "tags": { "": "string" }, "team_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "updated_at": "2026-09-15T14:30:00Z", "updated_by": "user@example.com", "user_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" }, "id": "33333333-3333-3333-3333-333333333333", "type": "rate-limits" } } ``` {% /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="409" %} Conflict {% 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 # 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 POST "https://api.${DD_SITE}/api/v2/rate-limits" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "mode": "ALERT", "name": "Default rate limit", "requests_per_minute": 600, "team_id": "00000000-0000-4000-8000-000000000002", "user_id": "00000000-0000-4000-8000-000000000001" }, "type": "rate-limits" } } EOF ``` {% /tab %} {% /tabs %}