@@ -22245,7 +22245,7 @@ paths:
               properties:
                 dimensions:
                   items:
-                    description: Dimension name
+                    description: Dimension to group by (up to 2). Use the /meta endpoint for available dimensions.
                     example: model
                     type: string
                   maxItems: 2
@@ -22254,7 +22254,7 @@ paths:
                   items:
                     properties:
                       field:
-                        description: Dimension to filter on
+                        description: Dimension to filter on. Use the /meta endpoint for available dimensions.
                         example: model
                         type: string
                       operator:
@@ -22272,7 +22272,15 @@ paths:
                                 - format: double
                                   type: number
                             type: array
-                        description: Filter value (scalar or array depending on operator)
+                        description: >-
+                          Filter value (scalar or array depending on operator). Several dimensions are enriched in
+                          responses (returned as human-readable labels), but filters must use the underlying ID:
+                          `api_key_id` — numeric ID (from generation metadata) or key hash (64-char hex from GET
+                          /api/v1/keys, resolved server-side); `user` — Clerk user ID (e.g. "user_abc123"), not the
+                          display name; `workspace` — workspace UUID, not the workspace name; `app` — numeric app ID,
+                          not the app title; `model` — permaslug (e.g. "openai/gpt-4o"), not the display name. Other
+                          dimensions (provider, origin, country, etc.) are not enriched and accept the value as
+                          returned.
                     required:
                       - field
                       - operator
@@ -22375,6 +22383,13 @@ paths:
                           - row_count
                           - truncated
                         type: object
+                      warnings:
+                        description: >-
+                          Warnings about filter resolution issues (e.g. unresolvable api_key_id hashes). The query still
+                          runs normally; these inform the caller that some filter values could not be resolved.
+                        items:
+                          type: string
+                        type: array
                     required:
                       - data
                       - metadata