From f221dc15d2d7b249376c9c068197e205733b4b65 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 29 May 2026 09:10:16 +0000
Subject: [PATCH] Add metadata_cost_breakdown_key and metadataValueBreakdown to
 analytics API spec

Adds two new fields to the Request Analytics endpoint:

- `metadata_cost_breakdown_key` (request field on RequestLogQuery): when
  provided, the response includes a cost/request breakdown filtered to that
  specific metadata key.
- `metadataValueBreakdown` (response field on RequestAnalyticsResponse):
  array of key/value/label/requests/cost entries, ordered by cost descending,
  up to 50 entries.

https://claude.ai/code/session_01DJAvfB8L7GLPpAyNU6r9yz
---
 openapi.json | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/openapi.json b/openapi.json
index 81d13c1..6d0586a 100644
--- a/openapi.json
+++ b/openapi.json
@@ -16204,6 +16204,11 @@
               "desc"
             ],
             "description": "Sort direction. Must be provided together with sort_by."
+          },
+          "metadata_cost_breakdown_key": {
+            "type": "string",
+            "nullable": true,
+            "description": "When provided, the analytics response includes a `metadataValueBreakdown` array with cost and request counts for each value of this metadata key. Omit or pass null to get an aggregate breakdown across the top metadata keys."
           }
         },
         "example": {
@@ -16633,6 +16638,35 @@
                 }
               }
             }
+          },
+          "metadataValueBreakdown": {
+            "type": "array",
+            "description": "Cost and request count breakdown by metadata key-value pairs. When `metadata_cost_breakdown_key` is set in the request, all entries share that key and the `label` equals the value. Otherwise entries span the top key-value combinations and `label` is `key = value`. Ordered by cost descending; up to 50 entries.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "The metadata key."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "The metadata value."
+                },
+                "label": {
+                  "type": "string",
+                  "description": "Display label. Equals `value` when filtered to a single key; equals `key = value` in the aggregate view."
+                },
+                "requests": {
+                  "type": "integer",
+                  "description": "Number of requests with this key-value pair."
+                },
+                "cost": {
+                  "type": "number",
+                  "description": "Total cost for requests with this key-value pair, in USD."
+                }
+              }
+            }
           }
         }
       },
@@ -18421,4 +18455,4 @@
       "ApiKeyAuth": []
     }
   ]
-}
\ No newline at end of file
+}