Add AI Gateway rate limit summaries for all templates and spend limits

.generator/schemas/v2/openapi.yaml

@@ -10826,7 +10826,7 @@ components:
         - MAX
     AiGatewayNullableRoutingRuleTierOrdering:
       description: >-
-        How a tier orders its targets. Omission preserves the saved same-position tier on update; null resets to configured. New tiers default to configured. The weighted_affinity ordering distributes first-choice assignments by relative target weights and accepts only model targets with an explicit provider, without repeated provider and model pairs in the same tier. The `classified` ordering is allowed only in the first tier and requires a classifier, destination rubrics, and one default destination. Its targets are model targets that each name one provider, not "*". Besides the default, it needs 1 to 9 destinations, each with a different rubric. Classified routing is in Preview: saving a classified tier returns 403 Forbidden unless the feature is enabled for the organization.
+        How a tier orders its targets. Omission preserves the saved same-position tier on update; null resets to configured. New tiers default to configured. The weighted_affinity ordering distributes first-choice assignments by relative target weights and accepts only model targets with an explicit provider, without repeated provider and model pairs in the same tier. The `classified` ordering is allowed only in the first tier and requires a classifier, destination rubrics, and one default destination.
       enum:
         - configured
         - weighted_affinity
@@ -11356,6 +11356,14 @@ components:
     AiGatewayRateLimitAttributes:
       description: Attributes of an AI Gateway rate limit.
       properties:
+        cost_microcents_per_minute:
+          description: Maximum priced spend per rolling minute, in microcents of 1e-8 USD each, shared by all matching traffic, or per counter for a template rate limit. Null when this rule does not limit cost.
+          example: 100000000
+          format: int64
+          maximum: 10000000000000
+          minimum: 1
+          nullable: true
+          type: integer
         created_at:
           description: Creation timestamp.
           example: "2026-09-01T00:00:00Z"
@@ -11459,6 +11467,8 @@ components:
         - scope_restricted
         - name
         - tags
+        - is_template
+        - template_split_dims
         - mode
         - enabled
         - revision
@@ -11470,6 +11480,14 @@ components:
     AiGatewayRateLimitCreateAttributes:
       description: Attributes used to create an AI Gateway rate limit.
       properties:
+        cost_microcents_per_minute:
+          description: Maximum priced spend per rolling minute, in microcents of 1e-8 USD each. At most 10000000000000, that is $100,000. In `ENFORCE` mode, requests to a model with no pricing are rejected, because their cost can't be counted.
+          example: 100000000
+          format: int64
+          maximum: 10000000000000
+          minimum: 1
+          nullable: true
+          type: integer
         input_tokens_per_minute:
           description: Maximum input tokens per rolling minute.
           format: int64
@@ -11491,7 +11509,7 @@ components:
           nullable: true
           type: integer
         requests_per_minute:
-          description: Maximum requests per rolling minute. At least one of `requests_per_minute`, `input_tokens_per_minute`, and `output_tokens_per_minute` is required.
+          description: Maximum requests per rolling minute. At least one of `requests_per_minute`, `input_tokens_per_minute`, `output_tokens_per_minute`, and `cost_microcents_per_minute` is required.
           example: 600
           format: int64
           maximum: 10000000
@@ -11540,6 +11558,17 @@ components:
     AiGatewayRateLimitInstanceAttributes:
       description: One counter of a template rate limit and its live usage.
       properties:
+        cost_microcents:
+          description: Priced spend, in microcents, counted in the rolling one-minute window. 0 when the rate limit doesn't limit cost.
+          example: 25000000
+          format: int64
+          type: integer
+        cost_microcents_per_minute:
+          description: The rate limit's per-counter spend limit, in microcents. Null when it doesn't limit cost.
+          example: 100000000
+          format: int64
+          nullable: true
+          type: integer
         first_seen:
           description: When the gateway first recorded a request for this counter.
           example: "2026-10-28T10:00:00Z"
@@ -11561,7 +11590,7 @@ components:
           example: "v1|7:user_id=36:11111111-1111-1111-1111-111111111111"
           type: string
         last_seen:
-          description: When the gateway last recorded a request for this counter; up to a few minutes behind live traffic.
+          description: 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.
           example: "2026-10-28T10:05:00Z"
           format: date-time
           type: string
@@ -11684,7 +11713,7 @@ components:
       description: Aggregate of a template rate limit's counters.
       properties:
         instance_count:
-          description: Number of counters.
+          description: Number of counters that were near or at a limit, or limited a request, in the last hour. Counters with room to spare aren't recorded.
           example: 14
           format: int64
           type: integer
@@ -11734,6 +11763,17 @@ components:
         - max_utilization
         - truncated
       type: object
+    AiGatewayRateLimitInstancesSummaryListResponse:
+      description: Response containing the counter summary of every template rate limit in the organization.
+      properties:
+        data:
+          items:
+            $ref: "#/components/schemas/AiGatewayRateLimitInstancesSummaryResource"
+            description: The aggregate of one template rate limit's counters.
+          type: array
+      required:
+        - data
+      type: object
     AiGatewayRateLimitInstancesSummaryResource:
       description: Aggregate of a template rate limit's counters.
       properties:
@@ -11854,6 +11894,13 @@ components:
     AiGatewayRateLimitUpdateAttributes:
       description: Attributes used to update an AI Gateway rate limit. Only sent fields are changed.
       properties:
+        cost_microcents_per_minute:
+          description: Spend limit in microcents per rolling minute. Set to 0 to remove the cost limit. Null is ignored. At least one limit must remain.
+          format: int64
+          maximum: 10000000000000
+          minimum: 0
+          nullable: true
+          type: integer
         enabled:
           description: Whether this rate limit is active.
           type: boolean
@@ -11926,6 +11973,11 @@ components:
     AiGatewayRateLimitUsageAttributes:
       description: Live consumption of one AI Gateway rate limit.
       properties:
+        cost_microcents:
+          description: Priced spend, in microcents, counted in the rolling one-minute window. Only rules with a cost limit count it, so it is 0 for other rules and for the untracked and total entries.
+          example: 25000000
+          format: int64
+          type: integer
         input_tokens:
           description: Input tokens counted in the rolling one-minute window.
           example: 45000
@@ -12050,8 +12102,7 @@ components:
           example: gpt-6-luna
           type: string
         provider:
-          description: >-
-            Decision-model provider slug. It must name a provider of type `openai`, `baseten`, or `typesafe`, the provider types that serve a decision model. Omit together with model to preserve the saved selection.
+          description: Decision-model provider slug. Omit together with model to preserve the saved selection.
           example: openai
           type: string
       type: object
@@ -12303,14 +12354,13 @@ components:
           minimum: 1
           type: integer
         provider:
-          description: Provider slug. weighted_affinity and classified tiers require an explicit provider and do not allow "*".
+          description: Provider slug. weighted_affinity requires an explicit provider and does not allow "*".
           example: prod-us
           type: string
         reasoning_level:
           $ref: "#/components/schemas/AiGatewayRoutingReasoningLevel"
         rubric:
-          description: >-
-            Destination rubric in a classified tier: when the decision model picks this destination. Up to 300 characters after leading and trailing spaces are trimmed, and different for each destination in the tier. Omission preserves a saved value; null clears it. Must be absent on the default destination.
+          description: Destination rubric in a classified tier. Omission preserves a saved value; null clears it. Must be absent on the default destination.
           example: Short factual questions.
           maxLength: 300
           nullable: true
@@ -231141,6 +231191,62 @@ paths:
       x-unstable: |-
         **Note**: This endpoint is in Preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
+  /api/v2/rate-limits/instances/summary:
+    get:
+      description: Aggregate the counters of every template rate limit in the organization in one call, with one summary per template in the order the rate limit list returns them. Each summary is the one the single-template counter summary endpoint returns without split_dim, including scope_restricted and truncated. Rate limits with one shared allowance are left out. Summaries are cached for up to 15 seconds.
+      operationId: ListAiGatewayRateLimitInstancesSummaries
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                default:
+                  value:
+                    data:
+                      - attributes:
+                          instance_count: 14
+                          limited_requests: 25
+                          limiting_count: 2
+                          max_utilization: 1.2
+                          near_limit_count: 3
+                          rate_limit_id: 33333333-3333-3333-3333-333333333333
+                          scope_restricted: false
+                          truncated: false
+                          would_limit_requests: 0
+                        id: 33333333-3333-3333-3333-333333333333
+                        type: rate-limit-instances-summary
+                      - attributes:
+                          instance_count: 0
+                          limited_requests: 0
+                          limiting_count: 0
+                          max_utilization: 0
+                          near_limit_count: 0
+                          rate_limit_id: 44444444-4444-4444-4444-444444444444
+                          scope_restricted: true
+                          truncated: false
+                          would_limit_requests: 0
+                        id: 44444444-4444-4444-4444-444444444444
+                        type: rate-limit-instances-summary
+              schema:
+                $ref: "#/components/schemas/AiGatewayRateLimitInstancesSummaryListResponse"
+          description: OK
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - ai_gateway_config_read
+      summary: List AI Gateway rate limit counter summaries
+      tags:
+        - AI Gateway
+      x-permission:
+        operator: OR
+        permissions:
+          - ai_gateway_config_read
+      x-unstable: |-
+        **Note**: This endpoint is in Preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/rate-limits/usage:
     get:
       description: 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).
@@ -231344,7 +231450,7 @@ paths:
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/rate-limits/{id}/instances:
     get:
-      description: 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.
+      description: 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.
       operationId: ListAiGatewayRateLimitInstances
       parameters:
         - $ref: "#/components/parameters/AiGatewayRateLimitID"
@@ -231405,7 +231511,7 @@ paths:
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/rate-limits/{id}/instances/summary:
     get:
-      description: Aggregate a template rate limit's counters, including how many there are, how many are near or at their limit, and the fullest counter's utilization. Use split_dim to aggregate only counters that match every given dimension value. When the caller can't see the template's selector, every count is zero and scope_restricted is true. Summaries are cached for up to 15 seconds. Returns 503 when counter usage can't be read.
+      description: Aggregate a template rate limit's hot counters (those near or at a limit, or limiting, in the last hour), including how many there are, how many are near or at their limit, and the fullest counter's utilization. Use split_dim to aggregate only counters that match every given dimension value. When the caller can't see the template's selector, every count is zero and scope_restricted is true. Summaries are cached for up to 15 seconds. Returns 503 when counter usage can't be read.
       operationId: GetAiGatewayRateLimitInstancesSummary
       parameters:
         - $ref: "#/components/parameters/AiGatewayRateLimitID"

examples/v2/ai-gateway/CreateAiGatewayRateLimit.java

@@ -26,6 +26,7 @@ public static void main(String[] args) {
                 new AiGatewayRateLimitCreateData()
                     .attributes(
                         new AiGatewayRateLimitCreateAttributes()
+                            .costMicrocentsPerMinute(100000000L)
                             .inputTokensPerMinute(null)
                             .mode(AiGatewayRateLimitMode.ALERT)
                             .name("Default rate limit")

examples/v2/ai-gateway/ListAiGatewayRateLimitInstancesSummaries.java

@@ -0,0 +1,28 @@
+// List AI Gateway rate limit counter summaries returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.AiGatewayApi;
+import com.datadog.api.client.v2.model.AiGatewayRateLimitInstancesSummaryListResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
+    defaultClient.setUnstableOperationEnabled("v2.listAiGatewayRateLimitInstancesSummaries", true);
+    AiGatewayApi apiInstance = new AiGatewayApi(defaultClient);
+
+    try {
+      AiGatewayRateLimitInstancesSummaryListResponse result =
+          apiInstance.listAiGatewayRateLimitInstancesSummaries();
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println(
+          "Exception when calling AiGatewayApi#listAiGatewayRateLimitInstancesSummaries");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

examples/v2/ai-gateway/UpdateAiGatewayRateLimit.java

@@ -24,6 +24,7 @@ public static void main(String[] args) {
                 new AiGatewayRateLimitUpdateData()
                     .attributes(
                         new AiGatewayRateLimitUpdateAttributes()
+                            .costMicrocentsPerMinute(null)
                             .inputTokensPerMinute(null)
                             .mode(AiGatewayRateLimitMode.ALERT)
                             .outputTokensPerMinute(null)

src/main/java/com/datadog/api/client/ApiClient.java

@@ -1200,6 +1200,7 @@ public class ApiClient {
           put("v2.listAiGatewayProviderModels", false);
           put("v2.listAiGatewayProviders", false);
           put("v2.listAiGatewayRateLimitInstances", false);
+          put("v2.listAiGatewayRateLimitInstancesSummaries", false);
           put("v2.listAiGatewayRateLimits", false);
           put("v2.listAiGatewayRoutingRules", false);
           put("v2.overrideAiGatewayBudgetInstanceCapacity", false);