Vector Stores File Batches

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Cancel vector store file batch

post /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel

Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible.

Path Parameters

vector_store_id: string
batch_id: string

Returns

VectorStoreFileBatch object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_batch"
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store↗ that the File↗ is attached to.

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATCH_ID/cancel \
    -X POST \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "object": "vector_store.files_batch",
  "status": "in_progress",
  "vector_store_id": "vector_store_id"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -X POST

Response

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

Create vector store file batch

post /vector_stores/{vector_store_id}/file_batches

Create a vector store file batch.

Path Parameters

vector_store_id: string

Body Parameters

attributes: optional map[string or number or boolean] or null

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.
- string
- number
- boolean
chunking_strategy: optional FileChunkingStrategyParam

The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.
- AutoFileChunkingStrategyParam object { type }
  
  The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
  - type: "auto"
    
    Always auto.
    - "auto"
- StaticFileChunkingStrategyObjectParam object { static, type }
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - chunk_overlap_tokens: number
      
      The number of tokens that overlap between chunks. The default value is 400.
      
      Note that the overlap must not exceed half of max_chunk_size_tokens.
    - max_chunk_size_tokens: number
      
      The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
  - type: "static"
    
    Always static.
    - "static"
file_ids: optional array of string

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 array of object { file_id, attributes, chunking_strategy }

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.
- file_id: string
  
  A File↗ ID that the vector store should use. Useful for tools like file_search that can access files. For multi-file ingestion, we recommend file_batches↗ to minimize per-vector-store write requests.
- attributes: optional map[string or number or boolean] or null
  
  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.
  - string
  - number
  - boolean
- chunking_strategy: optional FileChunkingStrategyParam
  
  The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.

Returns

VectorStoreFileBatch object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_batch"
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store↗ that the File↗ is attached to.

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "object": "vector_store.files_batch",
  "status": "in_progress",
  "vector_store_id": "vector_store_id"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json \
    -H "OpenAI-Beta: assistants=v2" \
    -d '{
      "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
          }
        }
      ]
    }'

Response

{
  "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,
  }
}

List vector store files in a batch

get /vector_stores/{vector_store_id}/file_batches/{batch_id}/files

Returns a list of vector store files in a batch.

Path Parameters

vector_store_id: string
batch_id: string

Query Parameters

after: optional string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before: optional string

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
filter: optional "in_progress" or "completed" or "failed" or "cancelled"

Filter by file status. One of in_progress, completed, failed, cancelled.
- "in_progress"
- "completed"
- "failed"
- "cancelled"
limit: optional number

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order: optional "asc" or "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
- "asc"
- "desc"

Returns

data: array of VectorStoreFile
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store file was created.
- last_error: object { code, message } or null
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: "server_error" or "unsupported_file" or "invalid_file"
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: string
    
    A human-readable description of the error.
- object: "vector_store.file"
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store file, which can be either in_progress, completed, cancelled, or failed. The status completed indicates that the vector store file is ready for use.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- usage_bytes: number
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: string
  
  The ID of the vector store↗ that the File↗ is attached to.
- attributes: optional map[string or number or boolean] or null
  
  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.
  - string
  - number
  - boolean
- chunking_strategy: optional StaticFileChunkingStrategyObject or OtherFileChunkingStrategyObject
  
  The strategy used to chunk the file.
  - StaticFileChunkingStrategyObject object { static, type }
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: number
        
        The number of tokens that overlap between chunks. The default value is 400.
        
        Note that the overlap must not exceed half of max_chunk_size_tokens.
      - max_chunk_size_tokens: number
        
        The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.
    - type: "static"
      
      Always static.
      - "static"
  - OtherFileChunkingStrategyObject object { type }
    
    This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the chunking_strategy concept was introduced in the API.
    - type: "other"
      
      Always other.
      - "other"
first_id: string
has_more: boolean
last_id: string
object: string

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATCH_ID/files \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "last_error": {
        "code": "server_error",
        "message": "message"
      },
      "object": "vector_store.file",
      "status": "in_progress",
      "usage_bytes": 0,
      "vector_store_id": "vector_store_id",
      "attributes": {
        "foo": "string"
      },
      "chunking_strategy": {
        "static": {
          "chunk_overlap_tokens": 0,
          "max_chunk_size_tokens": 100
        },
        "type": "static"
      }
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    },
    {
      "id": "file-abc456",
      "object": "vector_store.file",
      "created_at": 1699061776,
      "vector_store_id": "vs_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

Retrieve vector store file batch

get /vector_stores/{vector_store_id}/file_batches/{batch_id}

Retrieves a vector store file batch.

Path Parameters

vector_store_id: string
batch_id: string

Returns

VectorStoreFileBatch object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_batch"
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store↗ that the File↗ is attached to.

Example

curl https://api.openai.com/v1/vector_stores/$VECTOR_STORE_ID/file_batches/$BATCH_ID \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "object": "vector_store.files_batch",
  "status": "in_progress",
  "vector_store_id": "vector_store_id"
}

Example

curl https://api.openai.com/v1/vector_stores/vs_abc123/file_batches/vsfb_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "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,
  }
}

Domain Types

Vector Store File Batch

VectorStoreFileBatch object { id, created_at, file_counts, 3 more }

A batch of files attached to a vector store.
- id: string
  
  The identifier, which can be referenced in API endpoints.
- created_at: number
  
  The Unix timestamp (in seconds) for when the vector store files batch was created.
- file_counts: object { cancelled, completed, failed, 2 more }
  - cancelled: number
    
    The number of files that where cancelled.
  - completed: number
    
    The number of files that have been processed.
  - failed: number
    
    The number of files that have failed to process.
  - in_progress: number
    
    The number of files that are currently being processed.
  - total: number
    
    The total number of files.
- object: "vector_store.files_batch"
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_batch"
- status: "in_progress" or "completed" or "cancelled" or "failed"
  
  The status of the vector store files batch, which can be either in_progress, completed, cancelled or failed.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: string
  
  The ID of the vector store↗ that the File↗ is attached to.