Implementation:Openai Openai node VectorStore FileBatches

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

Overview

The FileBatches resource class provides methods for creating, retrieving, cancelling, and polling vector store file batches through the OpenAI API.

Description

The FileBatches class extends APIResource and enables bulk operations on files within a vector store. Rather than attaching files to a vector store one at a time, file batches allow developers to submit multiple files for indexing in a single API call and then track the overall progress of the batch.

The class provides both low-level CRUD operations (create, retrieve, cancel, listFiles) and higher-level convenience methods (createAndPoll, poll, uploadAndPoll). The polling methods repeatedly check the batch status until it reaches a terminal state (completed, failed, or cancelled), respecting either a custom poll interval or the server-suggested interval from the openai-poll-after-ms response header.

The uploadAndPoll method is particularly powerful: it uploads files concurrently (with configurable concurrency limits), collects the resulting file IDs, and then creates a batch and polls until completion. All API calls include the OpenAI-Beta: assistants=v2 header required for the Assistants API v2.

Usage

Use this resource when you need to attach multiple files to a vector store at once. It is ideal for bulk indexing scenarios where many documents need to be processed together, and the uploadAndPoll convenience method simplifies the entire upload-and-wait workflow into a single call.

Code Reference

Source Location

• Repository: openai-node
• File: src/resources/vector-stores/file-batches.ts

Signature

class FileBatches extends APIResource {
  create(vectorStoreID: string, body: FileBatchCreateParams, options?: RequestOptions): APIPromise<VectorStoreFileBatch>;
  retrieve(batchID: string, params: FileBatchRetrieveParams, options?: RequestOptions): APIPromise<VectorStoreFileBatch>;
  cancel(batchID: string, params: FileBatchCancelParams, options?: RequestOptions): APIPromise<VectorStoreFileBatch>;
  createAndPoll(vectorStoreId: string, body: FileBatchCreateParams, options?: RequestOptions & { pollIntervalMs?: number }): Promise<VectorStoreFileBatch>;
  listFiles(batchID: string, params: FileBatchListFilesParams, options?: RequestOptions): PagePromise<VectorStoreFilesPage, VectorStoreFile>;
  poll(vectorStoreID: string, batchID: string, options?: RequestOptions & { pollIntervalMs?: number }): Promise<VectorStoreFileBatch>;
  uploadAndPoll(vectorStoreId: string, { files, fileIds }: { files: Uploadable[]; fileIds?: string[] }, options?: RequestOptions & { pollIntervalMs?: number; maxConcurrency?: number }): Promise<VectorStoreFileBatch>;
}

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
vectorStoreID	string	Yes	The ID of the vector store to create the file batch in.
body.file_ids	Array<string>	No	A list of File IDs for the vector store to use. Mutually exclusive with files.
body.files	Array<{ file_id: string; attributes?; chunking_strategy? }>	No	A list of file objects with per-file overrides. Mutually exclusive with file_ids.
body.attributes	number | boolean> | null	No	Up to 16 key-value pairs of metadata applied to all files in the batch.
body.chunking_strategy	FileChunkingStrategyParam	No	Chunking strategy (auto or static) applied to all files.
options.pollIntervalMs	number	No	Custom polling interval in milliseconds (default: 5000 or server-suggested).
options.maxConcurrency	number	No	Maximum concurrent file uploads (default: 5). Used by uploadAndPoll.

Outputs

Name	Type	Description
id	string	The identifier of the file batch.
created_at	number	Unix timestamp (seconds) when the batch was created.
status	'completed' | 'cancelled' | 'failed'	Current status of the batch.
vector_store_id	string	The ID of the parent vector store.
file_counts	FileCounts	Object with counts: cancelled, completed, failed, in_progress, total.
object	'vector_store.files_batch'	The object type identifier.

Usage Examples

import OpenAI from 'openai';

const client = new OpenAI();

// Create a file batch from existing file IDs and poll until done
const batch = await client.vectorStores.fileBatches.createAndPoll(
  'vs_abc123',
  { file_ids: ['file-abc123', 'file-def456'] },
);
console.log(batch.status); // 'completed'
console.log(batch.file_counts);

// Upload local files concurrently and poll until indexed
import fs from 'fs';

const batch2 = await client.vectorStores.fileBatches.uploadAndPoll(
  'vs_abc123',
  {
    files: [
      fs.createReadStream('document1.pdf'),
      fs.createReadStream('document2.pdf'),
    ],
  },
  { maxConcurrency: 3 },
);

// List files in a batch with filtering
const files = await client.vectorStores.fileBatches.listFiles(
  batch2.id,
  { vector_store_id: 'vs_abc123', filter: 'completed' },
);

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime