feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,3 +1,3 @@
 configured_endpoints: 55
-openapi_spec_hash: 3c5027a5bd3fb174b9b7f26bd5cb0eba
+openapi_spec_hash: 37c29bad42e8605b1c087d22c8d48f30
 config_hash: 48c3812186c899cdef23cc8de76bd2aa

src/codex/resources/projects/projects.py

@@ -564,8 +564,9 @@ def retrieve_analytics(
         self,
         project_id: str,
         *,
-        end: int | Omit = omit,
-        start: int | Omit = omit,
+        end: Optional[int] | Omit = omit,
+        metadata_filters: Optional[str] | Omit = omit,
+        start: Optional[int] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -574,12 +575,46 @@ def retrieve_analytics(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ProjectRetrieveAnalyticsResponse:
         """
-        Get Project Analytics Route
+        Retrieve analytics data for a project including queries, bad responses, and
+        answers published.
+
+            **Metadata Filtering:**
+            - Filter by custom metadata fields using key-value pairs
+            - Supports single values: `{"department": "Engineering"}`
+            - Supports multiple values: `{"priority": ["high", "medium"]}`
+            - Supports null/missing values: `{"department": []}` or `{"department": [null]}`
+
+            **Available Metadata Fields:**
+            - Only metadata keys that exist on query logs are returned in `metadata_fields`
+            - Fields with ≤12 unique values show as "select" type with checkbox options
+            - Fields with >12 unique values show as "input" type for text search
+            - Fields with no data are excluded from the response entirely
+
+            **Null Value Behavior:**
+            - Empty arrays `[]` are automatically converted to `[null]` to filter for records where the metadata field is missing or null
+            - Use `[null]` explicitly to filter for records where the field is missing or null
+            - Use `["value1", null, "value2"]` to include both specific values and null values
+            - Records match if the metadata field is null, missing from custom_metadata, or custom_metadata itself is null
+
+            **Date Filtering:**
+            - Provide `start` only: filter logs created at or after this timestamp
+            - Provide `end` only: filter logs created at or before this timestamp
+            - Provide both: filter logs created within the time range
+            - Provide neither: include all logs regardless of creation time
 
         Args:
-          end: End timestamp in seconds since epoch
+          end: Filter logs created at or before this timestamp (epoch seconds). Can be used
+              alone for upper-bound filtering.
 
-          start: Start timestamp in seconds since epoch
+          metadata_filters:
+              Metadata filters as JSON string. Examples:
+                      - Single value: '{"department": "Engineering"}'
+                      - Multiple values: '{"priority": ["high", "medium"]}'
+                      - Null/missing values: '{"department": []}' or '{"department": [null]}'
+                      - Mixed values: '{"status": ["active", null, "pending"]}'
+
+          start: Filter logs created at or after this timestamp (epoch seconds). Can be used
+              alone for lower-bound filtering.
 
           extra_headers: Send extra headers
 
@@ -601,6 +636,7 @@ def retrieve_analytics(
                 query=maybe_transform(
                     {
                         "end": end,
+                        "metadata_filters": metadata_filters,
                         "start": start,
                     },
                     project_retrieve_analytics_params.ProjectRetrieveAnalyticsParams,
@@ -1301,8 +1337,9 @@ async def retrieve_analytics(
         self,
         project_id: str,
         *,
-        end: int | Omit = omit,
-        start: int | Omit = omit,
+        end: Optional[int] | Omit = omit,
+        metadata_filters: Optional[str] | Omit = omit,
+        start: Optional[int] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -1311,12 +1348,46 @@ async def retrieve_analytics(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> ProjectRetrieveAnalyticsResponse:
         """
-        Get Project Analytics Route
+        Retrieve analytics data for a project including queries, bad responses, and
+        answers published.
+
+            **Metadata Filtering:**
+            - Filter by custom metadata fields using key-value pairs
+            - Supports single values: `{"department": "Engineering"}`
+            - Supports multiple values: `{"priority": ["high", "medium"]}`
+            - Supports null/missing values: `{"department": []}` or `{"department": [null]}`
+
+            **Available Metadata Fields:**
+            - Only metadata keys that exist on query logs are returned in `metadata_fields`
+            - Fields with ≤12 unique values show as "select" type with checkbox options
+            - Fields with >12 unique values show as "input" type for text search
+            - Fields with no data are excluded from the response entirely
+
+            **Null Value Behavior:**
+            - Empty arrays `[]` are automatically converted to `[null]` to filter for records where the metadata field is missing or null
+            - Use `[null]` explicitly to filter for records where the field is missing or null
+            - Use `["value1", null, "value2"]` to include both specific values and null values
+            - Records match if the metadata field is null, missing from custom_metadata, or custom_metadata itself is null
+
+            **Date Filtering:**
+            - Provide `start` only: filter logs created at or after this timestamp
+            - Provide `end` only: filter logs created at or before this timestamp
+            - Provide both: filter logs created within the time range
+            - Provide neither: include all logs regardless of creation time
 
         Args:
-          end: End timestamp in seconds since epoch
+          end: Filter logs created at or before this timestamp (epoch seconds). Can be used
+              alone for upper-bound filtering.
+
+          metadata_filters:
+              Metadata filters as JSON string. Examples:
+                      - Single value: '{"department": "Engineering"}'
+                      - Multiple values: '{"priority": ["high", "medium"]}'
+                      - Null/missing values: '{"department": []}' or '{"department": [null]}'
+                      - Mixed values: '{"status": ["active", null, "pending"]}'
 
-          start: Start timestamp in seconds since epoch
+          start: Filter logs created at or after this timestamp (epoch seconds). Can be used
+              alone for lower-bound filtering.
 
           extra_headers: Send extra headers
 
@@ -1338,6 +1409,7 @@ async def retrieve_analytics(
                 query=await async_maybe_transform(
                     {
                         "end": end,
+                        "metadata_filters": metadata_filters,
                         "start": start,
                     },
                     project_retrieve_analytics_params.ProjectRetrieveAnalyticsParams,

src/codex/types/project_retrieve_analytics_params.py

@@ -2,14 +2,30 @@
 
 from __future__ import annotations
 
+from typing import Optional
 from typing_extensions import TypedDict
 
 __all__ = ["ProjectRetrieveAnalyticsParams"]
 
 
 class ProjectRetrieveAnalyticsParams(TypedDict, total=False):
-    end: int
-    """End timestamp in seconds since epoch"""
+    end: Optional[int]
+    """Filter logs created at or before this timestamp (epoch seconds).
 
-    start: int
-    """Start timestamp in seconds since epoch"""
+    Can be used alone for upper-bound filtering.
+    """
+
+    metadata_filters: Optional[str]
+    """Metadata filters as JSON string.
+
+    Examples: - Single value: '{"department": "Engineering"}' - Multiple values:
+    '{"priority": ["high", "medium"]}' - Null/missing values: '{"department": []}'
+    or '{"department": [null]}' - Mixed values: '{"status": ["active", null,
+    "pending"]}'
+    """
+
+    start: Optional[int]
+    """Filter logs created at or after this timestamp (epoch seconds).
+
+    Can be used alone for lower-bound filtering.
+    """

src/codex/types/project_retrieve_analytics_response.py

@@ -1,6 +1,7 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Dict, List
+from typing import Dict, List, Optional
+from typing_extensions import Literal
 
 from .._models import BaseModel
 
@@ -11,6 +12,7 @@
     "BadResponses",
     "BadResponsesResponsesByType",
     "Queries",
+    "MetadataField",
 ]
 
 
@@ -44,9 +46,27 @@ class Queries(BaseModel):
     total: int
 
 
+class MetadataField(BaseModel):
+    field_type: Literal["select", "input"]
+    """Field type: 'select' for checkbox selection, 'input' for text input"""
+
+    key: str
+    """Metadata field key"""
+
+    values: Optional[List[Optional[str]]] = None
+    """Possible values for this metadata field (None if more than 12 values).
+
+    Array elements may include null to represent logs where the metadata key is
+    missing or null.
+    """
+
+
 class ProjectRetrieveAnalyticsResponse(BaseModel):
     answers_published: AnswersPublished
 
     bad_responses: BadResponses
 
     queries: Queries
+
+    metadata_fields: Optional[List[MetadataField]] = None
+    """Available metadata fields for filtering"""

tests/api_resources/test_projects.py

@@ -743,6 +743,7 @@ def test_method_retrieve_analytics_with_all_params(self, client: Codex) -> None:
         project = client.projects.retrieve_analytics(
             project_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
             end=0,
+            metadata_filters="metadata_filters",
             start=0,
         )
         assert_matches_type(ProjectRetrieveAnalyticsResponse, project, path=["response"])
@@ -1630,6 +1631,7 @@ async def test_method_retrieve_analytics_with_all_params(self, async_client: Asy
         project = await async_client.projects.retrieve_analytics(
             project_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
             end=0,
+            metadata_filters="metadata_filters",
             start=0,
         )
         assert_matches_type(ProjectRetrieveAnalyticsResponse, project, path=["response"])