Implementation:Openai Openai node Batches Resource

Knowledge Sources	Openai_Openai_node
Domains	SDK, Batches
Last Updated	2026-02-15 12:00 GMT

Overview

The Batches resource class provides methods for creating, retrieving, listing, and cancelling batch API operations for bulk request processing.

Description

Batches extends APIResource and exposes four methods for managing batch operations. The create method submits a new batch job from an uploaded JSONL file of requests, targeting a specific API endpoint (e.g., /v1/chat/completions, /v1/responses, /v1/embeddings) with a 24h completion window. The retrieve method fetches the current state of a batch by its ID. The list method returns a paginated cursor-based list of all batches in the organization. The cancel method initiates cancellation of an in-progress batch, which transitions through a cancelling state before reaching cancelled.

The module defines the Batch interface, which includes comprehensive status tracking with timestamps for each lifecycle phase (created, in_progress, finalizing, completed, failed, expired, cancelling, cancelled). Batches carry references to input and output files via input_file_id, output_file_id, and error_file_id. Request counts are tracked via the BatchRequestCounts interface (total, completed, failed). Token usage statistics are available through BatchUsage with detailed breakdowns for input (cached tokens) and output (reasoning tokens).

The BatchCreateParams interface requires three fields: completion_window (currently only '24h'), endpoint (the API path for all requests), and input_file_id (the uploaded JSONL file). Optional parameters include metadata for key-value annotations and output_expires_after for configuring output file expiration.

Usage

This resource is accessed as client.batches. Batch operations are used for high-volume, non-time-sensitive API workloads. Users first upload a JSONL file of requests via the Files API, then create a batch referencing that file. The batch processes asynchronously and results are retrieved from the output file.

Code Reference

Source Location

• Repository: openai-node
• File: src/resources/batches.ts
• Lines: 1-367

Signature

export class Batches extends APIResource {
  create(body: BatchCreateParams, options?: RequestOptions): APIPromise<Batch>;
  retrieve(batchID: string, options?: RequestOptions): APIPromise<Batch>;
  list(query?: BatchListParams | null, options?: RequestOptions): PagePromise<BatchesPage, Batch>;
  cancel(batchID: string, options?: RequestOptions): APIPromise<Batch>;
}

Import

import OpenAI from 'openai';
// Accessed via: client.batches.create(...), client.batches.retrieve(...), etc.

I/O Contract

Inputs (BatchCreateParams)

Name	Type	Required	Description
completion_window	'24h'	Yes	Time frame for batch processing (currently only '24h')
endpoint	string	Yes	API endpoint for all requests: '/v1/responses', '/v1/chat/completions', '/v1/embeddings', '/v1/completions', '/v1/moderations', '/v1/images/generations', or '/v1/images/edits'
input_file_id	string	Yes	ID of the uploaded JSONL file containing requests (up to 50,000 requests, up to 200 MB)
metadata	null	No	Up to 16 key-value pairs for annotations
output_expires_after	{ anchor: 'created_at'; seconds: number }	No	Expiration policy for output/error files (3600-2592000 seconds)

Outputs (Batch)

Name	Type	Description
id	string	Unique batch identifier
status	string	Current status: 'validating', 'in_progress', 'finalizing', 'completed', 'failed', 'expired', 'cancelling', or 'cancelled'
input_file_id	string	ID of the input JSONL file
output_file_id	undefined	ID of the output file with successful results
error_file_id	undefined	ID of the file containing error results
request_counts	BatchRequestCounts	Counts of total, completed, and failed requests
usage	BatchUsage	Token usage with input/output breakdowns
endpoint	string	The API endpoint used
completion_window	string	The processing time frame
created_at	number	Unix timestamp of creation
metadata	null	Attached key-value pairs

Usage Examples

Basic Usage

import OpenAI from 'openai';

const client = new OpenAI();

// Step 1: Upload a JSONL file of requests
const file = await client.files.create({
  file: fs.createReadStream('requests.jsonl'),
  purpose: 'batch',
});

// Step 2: Create a batch
const batch = await client.batches.create({
  input_file_id: file.id,
  endpoint: '/v1/chat/completions',
  completion_window: '24h',
});

console.log('Batch ID:', batch.id);
console.log('Status:', batch.status);

Retrieving and Monitoring

const batch = await client.batches.retrieve('batch_abc123');

console.log('Status:', batch.status);
console.log('Progress:', batch.request_counts);
// { total: 1000, completed: 750, failed: 2 }

if (batch.output_file_id) {
  // Download results
  const content = await client.files.content(batch.output_file_id);
}

Listing Batches

const batches = await client.batches.list({ limit: 10 });

for await (const batch of batches) {
  console.log(`${batch.id}: ${batch.status}`);
}

Cancelling a Batch

const cancelled = await client.batches.cancel('batch_abc123');
console.log('Status:', cancelled.status); // 'cancelling'

Related Pages

• Openai_Openai_node_Files_Create