feat(api): batch list endpoint (#781)

Author: stainless-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 62
+configured_endpoints: 63

api.md

@@ -378,4 +378,5 @@ Methods:
 
 - <code title="post /batches">client.batches.<a href="./src/resources/batches.ts">create</a>({ ...params }) -> Batch</code>
 - <code title="get /batches/{batch_id}">client.batches.<a href="./src/resources/batches.ts">retrieve</a>(batchId) -> Batch</code>
+- <code title="get /batches">client.batches.<a href="./src/resources/batches.ts">list</a>({ ...params }) -> BatchesPage</code>
 - <code title="post /batches/{batch_id}/cancel">client.batches.<a href="./src/resources/batches.ts">cancel</a>(batchId) -> Batch</code>

src/index.ts

@@ -302,7 +302,9 @@ export namespace OpenAI {
   export import Batch = API.Batch;
   export import BatchError = API.BatchError;
   export import BatchRequestCounts = API.BatchRequestCounts;
+  export import BatchesPage = API.BatchesPage;
   export import BatchCreateParams = API.BatchCreateParams;
+  export import BatchListParams = API.BatchListParams;
 
   export import ErrorObject = API.ErrorObject;
   export import FunctionDefinition = API.FunctionDefinition;

src/resources/batches.ts

@@ -2,7 +2,9 @@
 
 import * as Core from 'openai/core';
 import { APIResource } from 'openai/resource';
+import { isRequestOptions } from 'openai/core';
 import * as BatchesAPI from 'openai/resources/batches';
+import { CursorPage, type CursorPageParams } from 'openai/pagination';
 
 export class Batches extends APIResource {
   /**
@@ -19,6 +21,21 @@ export class Batches extends APIResource {
     return this._client.get(`/batches/${batchId}`, options);
   }
 
+  /**
+   * List your organization's batches.
+   */
+  list(query?: BatchListParams, options?: Core.RequestOptions): Core.PagePromise<BatchesPage, Batch>;
+  list(options?: Core.RequestOptions): Core.PagePromise<BatchesPage, Batch>;
+  list(
+    query: BatchListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<BatchesPage, Batch> {
+    if (isRequestOptions(query)) {
+      return this.list({}, query);
+    }
+    return this._client.getAPIList('/batches', BatchesPage, { query, ...options });
+  }
+
   /**
    * Cancels an in-progress batch.
    */
@@ -27,6 +44,8 @@ export class Batches extends APIResource {
   }
 }
 
+export class BatchesPage extends CursorPage<Batch> {}
+
 export interface Batch {
   id: string;
 
@@ -217,9 +236,13 @@ export interface BatchCreateParams {
   metadata?: Record<string, string> | null;
 }
 
+export interface BatchListParams extends CursorPageParams {}
+
 export namespace Batches {
   export import Batch = BatchesAPI.Batch;
   export import BatchError = BatchesAPI.BatchError;
   export import BatchRequestCounts = BatchesAPI.BatchRequestCounts;
+  export import BatchesPage = BatchesAPI.BatchesPage;
   export import BatchCreateParams = BatchesAPI.BatchCreateParams;
+  export import BatchListParams = BatchesAPI.BatchListParams;
 }

src/resources/index.ts

@@ -3,7 +3,15 @@
 export * from './chat/index';
 export * from './shared';
 export { Audio } from './audio/audio';
-export { Batch, BatchError, BatchRequestCounts, BatchCreateParams, Batches } from './batches';
+export {
+  Batch,
+  BatchError,
+  BatchRequestCounts,
+  BatchCreateParams,
+  BatchListParams,
+  BatchesPage,
+  Batches,
+} from './batches';
 export { Beta } from './beta/beta';
 export {
   Completion,

tests/api-resources/batches.test.ts

@@ -51,6 +51,31 @@ describe('resource batches', () => {
     );
   });
 
+  test('list', async () => {
+    const responsePromise = openai.batches.list();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  test('list: request options instead of params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(openai.batches.list({ path: '/_stainless_unknown_path' })).rejects.toThrow(
+      OpenAI.NotFoundError,
+    );
+  });
+
+  test('list: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      openai.batches.list({ after: 'string', limit: 0 }, { path: '/_stainless_unknown_path' }),
+    ).rejects.toThrow(OpenAI.NotFoundError);
+  });
+
   test('cancel', async () => {
     const responsePromise = openai.batches.cancel('string');
     const rawResponse = await responsePromise.asResponse();