API Reference

Vector Stores

File Batches

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create vector store file batch

vector_stores.file_batches.create(strvector_store_id, FileBatchCreateParams**kwargs) -> VectorStoreFileBatch

POST/vector_stores/{vector_store_id}/file_batches

Create a vector store file batch.

ParametersExpand Collapse

vector_store_id: str

attributes: Optional[Dict[str, Union[str, float, bool]]]

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.

chunking_strategy: Optional[FileChunkingStrategyParam]

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy. Only applicable if file_ids is non-empty.

file_ids: Optional[Sequence[str]]

A list of File IDs that the vector store should use. Useful for tools like file_search that can access files. If attributes or chunking_strategy are provided, they will be applied to all files in the batch. The maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with files.

files: Optional[Iterable[File]]

A list of objects that each include a file_id plus optional attributes or chunking_strategy. Use this when you need to override metadata for specific files. The global attributes or chunking_strategy will be ignored and must be specified for each file. The maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with file_ids.

ReturnsExpand Collapse

class VectorStoreFileBatch: …

A batch of files attached to a vector store.

id: str

The identifier, which can be referenced in API endpoints.

created_at: int

The Unix timestamp (in seconds) for when the vector store files batch was created.

formatunixtime

file_counts: FileCounts

object: Literal["vector_store.files_batch"]

The object type, which is always vector_store.file_batch.

status: Literal["in_progress", "completed", "cancelled", "failed"]

The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.

vector_store_id: str

The ID of the vector store that the File is attached to.

Create vector store file batch

Python

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

from openai import OpenAI
client = OpenAI()

vector_store_file_batch = client.vector_stores.file_batches.create(
  vector_store_id="vs_abc123",
  files=[
    {
      "file_id": "file-abc123",
      "attributes": {"category": "finance"},
    },
    {
      "file_id": "file-abc456",
      "chunking_strategy": {
        "type": "static",
        "max_chunk_size_tokens": 1200,
        "chunk_overlap_tokens": 200,
      },
    },
  ],
)
print(vector_store_file_batch)

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0,
  }
}

Returns Examples

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "in_progress",
  "file_counts": {
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "cancelled": 0,
    "total": 0,
  }
}