From 840de279350efdc749907bf3d29c5ba0f2621d94 Mon Sep 17 00:00:00 2001
From: Justin Beckwith <jbeckwith@openai.com>
Date: Wed, 28 Oct 2026 11:39:31 +0000
Subject: [PATCH] feat(api): filter agent sessions by metadata

Castiron-Internal-PR: https://github.com/openai/openai-node-internal/pull/407
Castiron-Source-SHA: 7dcb536aba348b22fb474ff54191066fa00709e3
Castiron-Public-Base-SHA: d6c84252c9c55f1e047104d1dc3e0ac896bae38c
---
 .castiron.stats.yml                            | 10 +++++-----
 api_reference/openapi.transformed.yml          | 18 ++++++++++++++++++
 scripts/castiron/generated-files.json          |  4 ++--
 src/resources/beta/agents/sessions/sessions.ts | 10 +++++++++-
 .../beta/agents/sessions/sessions.test.ts      |  1 +
 5 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/.castiron.stats.yml b/.castiron.stats.yml
index d9aa069ce6..5974f16c77 100644
--- a/.castiron.stats.yml
+++ b/.castiron.stats.yml
@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: a7e57032-d27d-48a3-8369-86ac183c1c69
-openapi_spec_hash: 0fa065837f86231ded0decb63dbdf0b7
-openapi_transformed_spec_hash: 56311e2848d7e223897e87450386621c
+generation_id: 6ad22e41-f8ac-4742-a376-c4fa7138f3ea
+openapi_spec_hash: 7b8e0964b34b0cf993d2e2946e8eac7a
+openapi_transformed_spec_hash: 2e5cad7379e2d90af0d91139bb2d3333
 config_hash: c504b91d0d2bff67085cca331d9ad209
-codegen_sha: b8eda29979a71e324dae3e5888b5e9277b86bc50
-codegen_hash: ef0001ba574b6ca8564d676bfeb592de087e42a10a1e53e243dd0e3a5900950b
+codegen_sha: 2437018cf842c6666b53169433c8741b2f8ad0d6
+codegen_hash: e9c19ac1312d42abbb99e5dedd3c142b030562edd0eb3b81a48c9033d1e8ed8c
diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml
index 22590dfa89..01e001338b 100644
--- a/api_reference/openapi.transformed.yml
+++ b/api_reference/openapi.transformed.yml
@@ -33179,6 +33179,24 @@ paths:
           minLength: 0
           maxLength: 1048576
         description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents.
+      - name: metadata
+        in: query
+        required: false
+        schema:
+          type: object
+          additionalProperties:
+            type: string
+            minLength: 0
+            maxLength: 512
+          propertyNames:
+            type: string
+            minLength: 1
+            maxLength: 64
+          minProperties: 0
+          maxProperties: 16
+        description: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. New sessions and metadata updates may take time to appear in filtered results.
+        style: deepObject
+        explode: true
       responses:
         '200':
           description: A page of sessions.
diff --git a/scripts/castiron/generated-files.json b/scripts/castiron/generated-files.json
index 5246d27d60..7dda7f5c54 100644
--- a/scripts/castiron/generated-files.json
+++ b/scripts/castiron/generated-files.json
@@ -327,7 +327,7 @@
     },
     "src/resources/beta/agents/sessions/sessions.ts": {
       "mode": "100644",
-      "sha256": "9ba36d2ffec97b6aeaf1b7b3ede5bf6eefa06f2e8d427610613aea8fbe340011"
+      "sha256": "51e48fe4066d9dbaabb2dcadbaff5176d9def697ea57af9a48e80ca35cbe28b0"
     },
     "src/resources/beta/agents/sessions/subagents.ts": {
       "mode": "100644",
@@ -1175,7 +1175,7 @@
     },
     "tests/api-resources/beta/agents/sessions/sessions.test.ts": {
       "mode": "100644",
-      "sha256": "0dce16789849a21f6357a8d0f165666a3da2a96a362a8661e20f2884bf27afa9"
+      "sha256": "bcfe27c25052097d7f90925a15d2c28759d2f660aeed13d3410294485c773f75"
     },
     "tests/api-resources/beta/agents/sessions/subagents/items.test.ts": {
       "mode": "100644",
diff --git a/src/resources/beta/agents/sessions/sessions.ts b/src/resources/beta/agents/sessions/sessions.ts
index 58a4ffac04..85bd6188a3 100644
--- a/src/resources/beta/agents/sessions/sessions.ts
+++ b/src/resources/beta/agents/sessions/sessions.ts
@@ -381,7 +381,7 @@ export class Sessions extends APIResource {
   ): PagePromise<AgentSessionsPage, AgentsAPI.AgentSession> {
     const normalizeRequestOptionsForQueryOptions = normalizeRequestOptionsForQuery(
       query,
-      ['after', 'agent_id', 'limit', 'order'],
+      ['after', 'agent_id', 'limit', 'metadata', 'order'],
       options,
     );
     if (normalizeRequestOptionsForQueryOptions !== undefined) {
@@ -647,6 +647,14 @@ export interface SessionListParams extends CursorPageParams {
    */
   agent_id?: string;
 
+  /**
+   * Exact string matches supplied as `metadata[key]=value`. All supplied pairs must
+   * match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512
+   * characters. New sessions and metadata updates may take time to appear in
+   * filtered results.
+   */
+  metadata?: { [key: string]: string };
+
   /**
    * The order in which resources are returned. Defaults to `desc`.
    *
diff --git a/tests/api-resources/beta/agents/sessions/sessions.test.ts b/tests/api-resources/beta/agents/sessions/sessions.test.ts
index 43df05a183..593da784b0 100644
--- a/tests/api-resources/beta/agents/sessions/sessions.test.ts
+++ b/tests/api-resources/beta/agents/sessions/sessions.test.ts
@@ -112,6 +112,7 @@ describe('resource sessions', () => {
           after: 'after',
           agent_id: 'agent_id',
           limit: 1,
+          metadata: { foo: 'string' },
           order: 'asc',
         },
         { path: '/_stainless_unknown_path' },