Vector Stores

List vector stores

vector_stores.list(VectorStoreListParams**kwargs) -> SyncCursorPage[VectorStore]

get /vector_stores

Returns a list of vector stores.

Parameters

after: Optional[str]

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[str]

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.
limit: Optional[int]

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

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

Returns

class VectorStore: …

A vector store is a collection of processed files can be used by the file_search tool.
- id: str
  
  The identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that were cancelled.
  - completed: int
    
    The number of files that have been successfully processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- last_active_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: Optional[Metadata]
  
  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.
- name: str
  
  The name of the vector store.
- object: Literal["vector_store"]
  
  The object type, which is always vector_store.
  - "vector_store"
- status: Literal["expired", "in_progress", "completed"]
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: int
  
  The total number of bytes used by the files in the vector store.
- expires_after: Optional[ExpiresAfter]
  
  The expiration policy for a vector store.
  - anchor: Literal["last_active_at"]
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
    - "last_active_at"
  - days: int
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.vector_stores.list()
page = page.data[0]
print(page.id)

Response

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "file_counts": {
        "cancelled": 0,
        "completed": 0,
        "failed": 0,
        "in_progress": 0,
        "total": 0
      },
      "last_active_at": 0,
      "metadata": {
        "foo": "string"
      },
      "name": "name",
      "object": "vector_store",
      "status": "expired",
      "usage_bytes": 0,
      "expires_after": {
        "anchor": "last_active_at",
        "days": 1
      },
      "expires_at": 0
    }
  ],
  "first_id": "vs_abc123",
  "has_more": false,
  "last_id": "vs_abc456",
  "object": "list"
}

Example

from openai import OpenAI
client = OpenAI()

vector_stores = client.vector_stores.list()
print(vector_stores)

Response

{
  "object": "list",
  "data": [
    {
      "id": "vs_abc123",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ",
      "description": "Contains commonly asked questions and answers, organized by topic.",
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    },
    {
      "id": "vs_abc456",
      "object": "vector_store",
      "created_at": 1699061776,
      "name": "Support FAQ v2",
      "description": null,
      "bytes": 139920,
      "file_counts": {
        "in_progress": 0,
        "completed": 3,
        "failed": 0,
        "cancelled": 0,
        "total": 3
      }
    }
  ],
  "first_id": "vs_abc123",
  "last_id": "vs_abc456",
  "has_more": false
}

Create vector store

vector_stores.create(VectorStoreCreateParams**kwargs) -> VectorStore

post /vector_stores

Create a vector store.

Parameters

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.
- class AutoFileChunkingStrategyParam: …
  
  The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
  - type: Literal["auto"]
    
    Always auto.
    - "auto"
- class StaticFileChunkingStrategyObjectParam: …
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - chunk_overlap_tokens: int
      
      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: int
      
      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: Literal["static"]
    
    Always static.
    - "static"
description: Optional[str]

A description for the vector store. Can be used to describe the vector store's purpose.
expires_after: Optional[ExpiresAfter]

The expiration policy for a vector store.
- anchor: Literal["last_active_at"]
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - "last_active_at"
- days: int
  
  The number of days after the anchor time that the vector store will expire.
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.
metadata: Optional[Metadata]

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.
name: Optional[str]

The name of the vector store.

Returns

class VectorStore: …

A vector store is a collection of processed files can be used by the file_search tool.
- id: str
  
  The identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that were cancelled.
  - completed: int
    
    The number of files that have been successfully processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- last_active_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: Optional[Metadata]
  
  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.
- name: str
  
  The name of the vector store.
- object: Literal["vector_store"]
  
  The object type, which is always vector_store.
  - "vector_store"
- status: Literal["expired", "in_progress", "completed"]
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: int
  
  The total number of bytes used by the files in the vector store.
- expires_after: Optional[ExpiresAfter]
  
  The expiration policy for a vector store.
  - anchor: Literal["last_active_at"]
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
    - "last_active_at"
  - days: int
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store = client.vector_stores.create()
print(vector_store.id)

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vector_store",
  "status": "expired",
  "usage_bytes": 0,
  "expires_after": {
    "anchor": "last_active_at",
    "days": 1
  },
  "expires_at": 0
}

Example

from openai import OpenAI
client = OpenAI()

vector_store = client.vector_stores.create(
  name="Support FAQ"
)
print(vector_store)

Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "description": "Contains commonly asked questions and answers, organized by topic.",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

Retrieve vector store

vector_stores.retrieve(strvector_store_id) -> VectorStore

get /vector_stores/{vector_store_id}

Retrieves a vector store.

Parameters

vector_store_id: str

Returns

class VectorStore: …

A vector store is a collection of processed files can be used by the file_search tool.
- id: str
  
  The identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that were cancelled.
  - completed: int
    
    The number of files that have been successfully processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- last_active_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: Optional[Metadata]
  
  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.
- name: str
  
  The name of the vector store.
- object: Literal["vector_store"]
  
  The object type, which is always vector_store.
  - "vector_store"
- status: Literal["expired", "in_progress", "completed"]
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: int
  
  The total number of bytes used by the files in the vector store.
- expires_after: Optional[ExpiresAfter]
  
  The expiration policy for a vector store.
  - anchor: Literal["last_active_at"]
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
    - "last_active_at"
  - days: int
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store = client.vector_stores.retrieve(
    "vector_store_id",
)
print(vector_store.id)

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vector_store",
  "status": "expired",
  "usage_bytes": 0,
  "expires_after": {
    "anchor": "last_active_at",
    "days": 1
  },
  "expires_at": 0
}

Example

from openai import OpenAI
client = OpenAI()

vector_store = client.vector_stores.retrieve(
  vector_store_id="vs_abc123"
)
print(vector_store)

Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776
}

Modify vector store

vector_stores.update(strvector_store_id, VectorStoreUpdateParams**kwargs) -> VectorStore

post /vector_stores/{vector_store_id}

Modifies a vector store.

Parameters

vector_store_id: str
expires_after: Optional[ExpiresAfter]

The expiration policy for a vector store.
- anchor: Literal["last_active_at"]
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
  - "last_active_at"
- days: int
  
  The number of days after the anchor time that the vector store will expire.
metadata: Optional[Metadata]

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.
name: Optional[str]

The name of the vector store.

Returns

class VectorStore: …

A vector store is a collection of processed files can be used by the file_search tool.
- id: str
  
  The identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that were cancelled.
  - completed: int
    
    The number of files that have been successfully processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- last_active_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: Optional[Metadata]
  
  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.
- name: str
  
  The name of the vector store.
- object: Literal["vector_store"]
  
  The object type, which is always vector_store.
  - "vector_store"
- status: Literal["expired", "in_progress", "completed"]
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: int
  
  The total number of bytes used by the files in the vector store.
- expires_after: Optional[ExpiresAfter]
  
  The expiration policy for a vector store.
  - anchor: Literal["last_active_at"]
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
    - "last_active_at"
  - days: int
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store = client.vector_stores.update(
    vector_store_id="vector_store_id",
)
print(vector_store.id)

Response

{
  "id": "id",
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vector_store",
  "status": "expired",
  "usage_bytes": 0,
  "expires_after": {
    "anchor": "last_active_at",
    "days": 1
  },
  "expires_at": 0
}

Example

from openai import OpenAI
client = OpenAI()

vector_store = client.vector_stores.update(
  vector_store_id="vs_abc123",
  name="Support FAQ"
)
print(vector_store)

Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Support FAQ",
  "description": "Contains commonly asked questions and answers, organized by topic.",
  "bytes": 139920,
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 0,
    "total": 3
  }
}

Delete vector store

vector_stores.delete(strvector_store_id) -> VectorStoreDeleted

delete /vector_stores/{vector_store_id}

Delete a vector store.

Parameters

vector_store_id: str

Returns

class VectorStoreDeleted: …
- id: str
- deleted: bool
- object: Literal["vector_store.deleted"]
  - "vector_store.deleted"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_deleted = client.vector_stores.delete(
    "vector_store_id",
)
print(vector_store_deleted.id)

Response

{
  "id": "id",
  "deleted": true,
  "object": "vector_store.deleted"
}

Example

from openai import OpenAI
client = OpenAI()

deleted_vector_store = client.vector_stores.delete(
  vector_store_id="vs_abc123"
)
print(deleted_vector_store)

Response

{
  id: "vs_abc123",
  object: "vector_store.deleted",
  deleted: true
}

Search vector store

vector_stores.search(strvector_store_id, VectorStoreSearchParams**kwargs) -> SyncPage[VectorStoreSearchResponse]

post /vector_stores/{vector_store_id}/search

Search a vector store for relevant chunks based on a query and file attributes filter.

Parameters

vector_store_id: str
query: Union[str, Sequence[str]]

A query string for a search
- str
- Sequence[str]
filters: Optional[Filters]

A filter to apply based on file attributes.
- class ComparisonFilter: …
  
  A filter used to compare a specified attribute key to a given value using a defined comparison operation.
  - key: str
    
    The key to compare against the value.
  - type: Literal["eq", "ne", "gt", 5 more]
    
    Specifies the comparison operator: eq, ne, gt, gte, lt, lte, in, nin.
    - eq: equals
    - ne: not equal
    - gt: greater than
    - gte: greater than or equal
    - lt: less than
    - lte: less than or equal
    - in: in
    - nin: not in
    - "eq"
    - "ne"
    - "gt"
    - "gte"
    - "lt"
    - "lte"
    - "in"
    - "nin"
  - value: Union[str, float, bool, List[Union[str, float]]]
    
    The value to compare against the attribute key; supports string, number, or boolean types.
    - str
    - float
    - bool
    - List[Union[str, float]]
      - str
      - float
- class CompoundFilter: …
  
  Combine multiple filters using and or or.
  - filters: List[Filter]
    
    Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
    - class ComparisonFilter: …
      
      A filter used to compare a specified attribute key to a given value using a defined comparison operation.
    - object
  - type: Literal["and", "or"]
    
    Type of operation: and or or.
    - "and"
    - "or"
max_num_results: Optional[int]

The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options: Optional[RankingOptions]

Ranking options for search.
- ranker: Optional[Literal["none", "auto", "default-2024-11-15"]]
  
  Enable re-ranking; set to none to disable, which can help reduce latency.
  - "none"
  - "auto"
  - "default-2024-11-15"
- score_threshold: Optional[float]
rewrite_query: Optional[bool]

Whether to rewrite the natural language query for vector search.

Returns

class VectorStoreSearchResponse: …
- 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.
  - str
  - float
  - bool
- content: List[Content]
  
  Content chunks from the file.
  - text: str
    
    The text content returned from search.
  - type: Literal["text"]
    
    The type of content.
    - "text"
- file_id: str
  
  The ID of the vector store file.
- filename: str
  
  The name of the vector store file.
- score: float
  
  The similarity score for the result.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.vector_stores.search(
    vector_store_id="vs_abc123",
    query="string",
)
page = page.data[0]
print(page.file_id)

Response

{
  "data": [
    {
      "attributes": {
        "foo": "string"
      },
      "content": [
        {
          "text": "text",
          "type": "text"
        }
      ],
      "file_id": "file_id",
      "filename": "filename",
      "score": 0
    }
  ],
  "has_more": true,
  "next_page": "next_page",
  "object": "vector_store.search_results.page",
  "search_query": [
    "string"
  ]
}

Domain Types

Auto File Chunking Strategy Param

class AutoFileChunkingStrategyParam: …

The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
- type: Literal["auto"]
  
  Always auto.
  - "auto"

File Chunking Strategy

FileChunkingStrategy

The strategy used to chunk the file.
- class StaticFileChunkingStrategyObject: …
  - static: StaticFileChunkingStrategy
    - chunk_overlap_tokens: int
      
      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: int
      
      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: Literal["static"]
    
    Always static.
    - "static"
- class OtherFileChunkingStrategyObject: …
  
  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: Literal["other"]
    
    Always other.
    - "other"

File Chunking Strategy Param

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.
- class AutoFileChunkingStrategyParam: …
  
  The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
  - type: Literal["auto"]
    
    Always auto.
    - "auto"
- class StaticFileChunkingStrategyObjectParam: …
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - chunk_overlap_tokens: int
      
      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: int
      
      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: Literal["static"]
    
    Always static.
    - "static"

Other File Chunking Strategy Object

class OtherFileChunkingStrategyObject: …

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: Literal["other"]
  
  Always other.
  - "other"

Static File Chunking Strategy

class StaticFileChunkingStrategy: …
- chunk_overlap_tokens: int
  
  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: int
  
  The maximum number of tokens in each chunk. The default value is 800. The minimum value is 100 and the maximum value is 4096.

Static File Chunking Strategy Object

class StaticFileChunkingStrategyObject: …
- static: StaticFileChunkingStrategy
  - chunk_overlap_tokens: int
    
    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: int
    
    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: Literal["static"]
  
  Always static.
  - "static"

Static File Chunking Strategy Object Param

class StaticFileChunkingStrategyObjectParam: …

Customize your own chunking strategy by setting chunk size and chunk overlap.
- static: StaticFileChunkingStrategy
  - chunk_overlap_tokens: int
    
    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: int
    
    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: Literal["static"]
  
  Always static.
  - "static"

Vector Store

class VectorStore: …

A vector store is a collection of processed files can be used by the file_search tool.
- id: str
  
  The identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the vector store was created.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that were cancelled.
  - completed: int
    
    The number of files that have been successfully processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- last_active_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store was last active.
- metadata: Optional[Metadata]
  
  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.
- name: str
  
  The name of the vector store.
- object: Literal["vector_store"]
  
  The object type, which is always vector_store.
  - "vector_store"
- status: Literal["expired", "in_progress", "completed"]
  
  The status of the vector store, which can be either expired, in_progress, or completed. A status of completed indicates that the vector store is ready for use.
  - "expired"
  - "in_progress"
  - "completed"
- usage_bytes: int
  
  The total number of bytes used by the files in the vector store.
- expires_after: Optional[ExpiresAfter]
  
  The expiration policy for a vector store.
  - anchor: Literal["last_active_at"]
    
    Anchor timestamp after which the expiration policy applies. Supported anchors: last_active_at.
    - "last_active_at"
  - days: int
    
    The number of days after the anchor time that the vector store will expire.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the vector store will expire.

Vector Store Deleted

class VectorStoreDeleted: …
- id: str
- deleted: bool
- object: Literal["vector_store.deleted"]
  - "vector_store.deleted"

Vector Store Search Response

class VectorStoreSearchResponse: …
- 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.
  - str
  - float
  - bool
- content: List[Content]
  
  Content chunks from the file.
  - text: str
    
    The text content returned from search.
  - type: Literal["text"]
    
    The type of content.
    - "text"
- file_id: str
  
  The ID of the vector store file.
- filename: str
  
  The name of the vector store file.
- score: float
  
  The similarity score for the result.

Files

List vector store files

vector_stores.files.list(strvector_store_id, FileListParams**kwargs) -> SyncCursorPage[VectorStoreFile]

get /vector_stores/{vector_store_id}/files

Returns a list of vector store files.

Parameters

vector_store_id: str
after: Optional[str]

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[str]

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[Literal["in_progress", "completed", "failed", "cancelled"]]

Filter by file status. One of in_progress, completed, failed, cancelled.
- "in_progress"
- "completed"
- "failed"
- "cancelled"
limit: Optional[int]

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

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

Returns

class VectorStoreFile: …

A list 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 file was created.
- last_error: Optional[LastError]
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: Literal["server_error", "unsupported_file", "invalid_file"]
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: str
    
    A human-readable description of the error.
- object: Literal["vector_store.file"]
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: Literal["in_progress", "completed", "cancelled", "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: int
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.
- 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.
  - str
  - float
  - bool
- chunking_strategy: Optional[FileChunkingStrategy]
  
  The strategy used to chunk the file.
  - class StaticFileChunkingStrategyObject: …
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: int
        
        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: int
        
        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: Literal["static"]
      
      Always static.
      - "static"
  - class OtherFileChunkingStrategyObject: …
    
    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: Literal["other"]
      
      Always other.
      - "other"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.vector_stores.files.list(
    vector_store_id="vector_store_id",
)
page = page.data[0]
print(page.id)

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

from openai import OpenAI
client = OpenAI()

vector_store_files = client.vector_stores.files.list(
  vector_store_id="vs_abc123"
)
print(vector_store_files)

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
}

Create vector store file

vector_stores.files.create(strvector_store_id, FileCreateParams**kwargs) -> VectorStoreFile

post /vector_stores/{vector_store_id}/files

Create a vector store file by attaching a File to a vector store.

Parameters

vector_store_id: str
file_id: str

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[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.
- str
- float
- bool
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.
- class AutoFileChunkingStrategyParam: …
  
  The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
  - type: Literal["auto"]
    
    Always auto.
    - "auto"
- class StaticFileChunkingStrategyObjectParam: …
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - chunk_overlap_tokens: int
      
      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: int
      
      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: Literal["static"]
    
    Always static.
    - "static"

Returns

class VectorStoreFile: …

A list 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 file was created.
- last_error: Optional[LastError]
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: Literal["server_error", "unsupported_file", "invalid_file"]
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: str
    
    A human-readable description of the error.
- object: Literal["vector_store.file"]
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: Literal["in_progress", "completed", "cancelled", "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: int
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.
- 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.
  - str
  - float
  - bool
- chunking_strategy: Optional[FileChunkingStrategy]
  
  The strategy used to chunk the file.
  - class StaticFileChunkingStrategyObject: …
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: int
        
        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: int
        
        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: Literal["static"]
      
      Always static.
      - "static"
  - class OtherFileChunkingStrategyObject: …
    
    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: Literal["other"]
      
      Always other.
      - "other"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file = client.vector_stores.files.create(
    vector_store_id="vs_abc123",
    file_id="file_id",
)
print(vector_store_file.id)

Response

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

Example

from openai import OpenAI
client = OpenAI()

vector_store_file = client.vector_stores.files.create(
  vector_store_id="vs_abc123",
  file_id="file-abc123"
)
print(vector_store_file)

Response

{
  "id": "file-abc123",
  "object": "vector_store.file",
  "created_at": 1699061776,
  "usage_bytes": 1234,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null
}

Update vector store file attributes

vector_stores.files.update(strfile_id, FileUpdateParams**kwargs) -> VectorStoreFile

post /vector_stores/{vector_store_id}/files/{file_id}

Update attributes on a vector store file.

Parameters

vector_store_id: str
file_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.
- str
- float
- bool

Returns

class VectorStoreFile: …

A list 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 file was created.
- last_error: Optional[LastError]
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: Literal["server_error", "unsupported_file", "invalid_file"]
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: str
    
    A human-readable description of the error.
- object: Literal["vector_store.file"]
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: Literal["in_progress", "completed", "cancelled", "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: int
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.
- 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.
  - str
  - float
  - bool
- chunking_strategy: Optional[FileChunkingStrategy]
  
  The strategy used to chunk the file.
  - class StaticFileChunkingStrategyObject: …
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: int
        
        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: int
        
        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: Literal["static"]
      
      Always static.
      - "static"
  - class OtherFileChunkingStrategyObject: …
    
    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: Literal["other"]
      
      Always other.
      - "other"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file = client.vector_stores.files.update(
    file_id="file-abc123",
    vector_store_id="vs_abc123",
    attributes={
        "foo": "string"
    },
)
print(vector_store_file.id)

Response

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

Retrieve vector store file

vector_stores.files.retrieve(strfile_id, FileRetrieveParams**kwargs) -> VectorStoreFile

get /vector_stores/{vector_store_id}/files/{file_id}

Retrieves a vector store file.

Parameters

vector_store_id: str
file_id: str

Returns

class VectorStoreFile: …

A list 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 file was created.
- last_error: Optional[LastError]
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: Literal["server_error", "unsupported_file", "invalid_file"]
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: str
    
    A human-readable description of the error.
- object: Literal["vector_store.file"]
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: Literal["in_progress", "completed", "cancelled", "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: int
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.
- 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.
  - str
  - float
  - bool
- chunking_strategy: Optional[FileChunkingStrategy]
  
  The strategy used to chunk the file.
  - class StaticFileChunkingStrategyObject: …
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: int
        
        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: int
        
        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: Literal["static"]
      
      Always static.
      - "static"
  - class OtherFileChunkingStrategyObject: …
    
    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: Literal["other"]
      
      Always other.
      - "other"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file = client.vector_stores.files.retrieve(
    file_id="file-abc123",
    vector_store_id="vs_abc123",
)
print(vector_store_file.id)

Response

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

Example

from openai import OpenAI
client = OpenAI()

vector_store_file = client.vector_stores.files.retrieve(
  vector_store_id="vs_abc123",
  file_id="file-abc123"
)
print(vector_store_file)

Response

{
  "id": "file-abc123",
  "object": "vector_store.file",
  "created_at": 1699061776,
  "vector_store_id": "vs_abcd",
  "status": "completed",
  "last_error": null
}

Delete vector store file

vector_stores.files.delete(strfile_id, FileDeleteParams**kwargs) -> VectorStoreFileDeleted

delete /vector_stores/{vector_store_id}/files/{file_id}

Delete a vector store file. This will remove the file from the vector store but the file itself will not be deleted. To delete the file, use the delete file endpoint.

Parameters

vector_store_id: str
file_id: str

Returns

class VectorStoreFileDeleted: …
- id: str
- deleted: bool
- object: Literal["vector_store.file.deleted"]
  - "vector_store.file.deleted"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file_deleted = client.vector_stores.files.delete(
    file_id="file_id",
    vector_store_id="vector_store_id",
)
print(vector_store_file_deleted.id)

Response

{
  "id": "id",
  "deleted": true,
  "object": "vector_store.file.deleted"
}

Example

from openai import OpenAI
client = OpenAI()

deleted_vector_store_file = client.vector_stores.files.delete(
    vector_store_id="vs_abc123",
    file_id="file-abc123"
)
print(deleted_vector_store_file)

Response

{
  id: "file-abc123",
  object: "vector_store.file.deleted",
  deleted: true
}

Retrieve vector store file content

vector_stores.files.content(strfile_id, FileContentParams**kwargs) -> SyncPage[FileContentResponse]

get /vector_stores/{vector_store_id}/files/{file_id}/content

Retrieve the parsed contents of a vector store file.

Parameters

vector_store_id: str
file_id: str

Returns

class FileContentResponse: …
- text: Optional[str]
  
  The text content
- type: Optional[str]
  
  The content type (currently only "text")

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.vector_stores.files.content(
    file_id="file-abc123",
    vector_store_id="vs_abc123",
)
page = page.data[0]
print(page.text)

Response

{
  "data": [
    {
      "text": "text",
      "type": "type"
    }
  ],
  "has_more": true,
  "next_page": "next_page",
  "object": "vector_store.file_content.page"
}

Domain Types

Vector Store File

class VectorStoreFile: …

A list 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 file was created.
- last_error: Optional[LastError]
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: Literal["server_error", "unsupported_file", "invalid_file"]
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: str
    
    A human-readable description of the error.
- object: Literal["vector_store.file"]
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: Literal["in_progress", "completed", "cancelled", "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: int
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.
- 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.
  - str
  - float
  - bool
- chunking_strategy: Optional[FileChunkingStrategy]
  
  The strategy used to chunk the file.
  - class StaticFileChunkingStrategyObject: …
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: int
        
        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: int
        
        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: Literal["static"]
      
      Always static.
      - "static"
  - class OtherFileChunkingStrategyObject: …
    
    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: Literal["other"]
      
      Always other.
      - "other"

Vector Store File Deleted

class VectorStoreFileDeleted: …
- id: str
- deleted: bool
- object: Literal["vector_store.file.deleted"]
  - "vector_store.file.deleted"

File Content Response

class FileContentResponse: …
- text: Optional[str]
  
  The text content
- type: Optional[str]
  
  The content type (currently only "text")

File Batches

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.

Parameters

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.
- str
- float
- bool
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.
- class AutoFileChunkingStrategyParam: …
  
  The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.
  - type: Literal["auto"]
    
    Always auto.
    - "auto"
- class StaticFileChunkingStrategyObjectParam: …
  
  Customize your own chunking strategy by setting chunk size and chunk overlap.
  - static: StaticFileChunkingStrategy
    - chunk_overlap_tokens: int
      
      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: int
      
      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: Literal["static"]
    
    Always static.
    - "static"
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.
- file_id: str
  
  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[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.
  - str
  - float
  - bool
- 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.

Returns

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.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that where cancelled.
  - completed: int
    
    The number of files that have been processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- object: Literal["vector_store.files_batch"]
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file_batch = client.vector_stores.file_batches.create(
    vector_store_id="vs_abc123",
)
print(vector_store_file_batch.id)

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

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)

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

Retrieve vector store file batch

vector_stores.file_batches.retrieve(strbatch_id, FileBatchRetrieveParams**kwargs) -> VectorStoreFileBatch

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

Retrieves a vector store file batch.

Parameters

vector_store_id: str
batch_id: str

Returns

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.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that where cancelled.
  - completed: int
    
    The number of files that have been processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- object: Literal["vector_store.files_batch"]
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file_batch = client.vector_stores.file_batches.retrieve(
    batch_id="vsfb_abc123",
    vector_store_id="vs_abc123",
)
print(vector_store_file_batch.id)

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

from openai import OpenAI
client = OpenAI()

vector_store_file_batch = client.vector_stores.file_batches.retrieve(
  vector_store_id="vs_abc123",
  batch_id="vsfb_abc123"
)
print(vector_store_file_batch)

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

Cancel vector store file batch

vector_stores.file_batches.cancel(strbatch_id, FileBatchCancelParams**kwargs) -> VectorStoreFileBatch

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.

Parameters

vector_store_id: str
batch_id: str

Returns

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.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that where cancelled.
  - completed: int
    
    The number of files that have been processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- object: Literal["vector_store.files_batch"]
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
vector_store_file_batch = client.vector_stores.file_batches.cancel(
    batch_id="batch_id",
    vector_store_id="vector_store_id",
)
print(vector_store_file_batch.id)

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

from openai import OpenAI
client = OpenAI()

deleted_vector_store_file_batch = client.vector_stores.file_batches.cancel(
    vector_store_id="vs_abc123",
    file_batch_id="vsfb_abc123"
)
print(deleted_vector_store_file_batch)

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

List vector store files in a batch

vector_stores.file_batches.list_files(strbatch_id, FileBatchListFilesParams**kwargs) -> SyncCursorPage[VectorStoreFile]

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

Returns a list of vector store files in a batch.

Parameters

vector_store_id: str
batch_id: str
after: Optional[str]

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[str]

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[Literal["in_progress", "completed", "failed", "cancelled"]]

Filter by file status. One of in_progress, completed, failed, cancelled.
- "in_progress"
- "completed"
- "failed"
- "cancelled"
limit: Optional[int]

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

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

Returns

class VectorStoreFile: …

A list 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 file was created.
- last_error: Optional[LastError]
  
  The last error associated with this vector store file. Will be null if there are no errors.
  - code: Literal["server_error", "unsupported_file", "invalid_file"]
    
    One of server_error, unsupported_file, or invalid_file.
    - "server_error"
    - "unsupported_file"
    - "invalid_file"
  - message: str
    
    A human-readable description of the error.
- object: Literal["vector_store.file"]
  
  The object type, which is always vector_store.file.
  - "vector_store.file"
- status: Literal["in_progress", "completed", "cancelled", "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: int
  
  The total vector store usage in bytes. Note that this may be different from the original file size.
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.
- 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.
  - str
  - float
  - bool
- chunking_strategy: Optional[FileChunkingStrategy]
  
  The strategy used to chunk the file.
  - class StaticFileChunkingStrategyObject: …
    - static: StaticFileChunkingStrategy
      - chunk_overlap_tokens: int
        
        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: int
        
        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: Literal["static"]
      
      Always static.
      - "static"
  - class OtherFileChunkingStrategyObject: …
    
    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: Literal["other"]
      
      Always other.
      - "other"

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.vector_stores.file_batches.list_files(
    batch_id="batch_id",
    vector_store_id="vector_store_id",
)
page = page.data[0]
print(page.id)

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

from openai import OpenAI
client = OpenAI()

vector_store_files = client.vector_stores.file_batches.list_files(
  vector_store_id="vs_abc123",
  batch_id="vsfb_abc123"
)
print(vector_store_files)

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
}

Domain Types

Vector Store File Batch

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.
- file_counts: FileCounts
  - cancelled: int
    
    The number of files that where cancelled.
  - completed: int
    
    The number of files that have been processed.
  - failed: int
    
    The number of files that have failed to process.
  - in_progress: int
    
    The number of files that are currently being processed.
  - total: int
    
    The total number of files.
- object: Literal["vector_store.files_batch"]
  
  The object type, which is always vector_store.file_batch.
  - "vector_store.files_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.
  - "in_progress"
  - "completed"
  - "cancelled"
  - "failed"
- vector_store_id: str
  
  The ID of the vector store that the File is attached to.

python/resources/vector_stores/index.md +431 −35

6 6

7**get** `/vector_stores`7**get** `/vector_stores`

8 8

~~9List vector stores~~9Returns a list of vector stores.

10 10

11### Parameters11### Parameters

12 12

231 231

232**post** `/vector_stores`232**post** `/vector_stores`

233 233

234Create vector store234Create a vector store.

235 235

236### Parameters236### Parameters

237 237

238- `chunking_strategy: Optional[object]`238- `chunking_strategy: Optional[FileChunkingStrategyParam]`

239

240 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.

241

242 - `class AutoFileChunkingStrategyParam: …`

243

244 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.

245

246 - `type: Literal["auto"]`

247

248 Always `auto`.

249

250 - `"auto"`

251

252 - `class StaticFileChunkingStrategyObjectParam: …`

253

254 Customize your own chunking strategy by setting chunk size and chunk overlap.

255

256 - `static: StaticFileChunkingStrategy`

257

258 - `chunk_overlap_tokens: int`

259

260 The number of tokens that overlap between chunks. The default value is `400`.

261

262 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

263

264 - `max_chunk_size_tokens: int`

265

266 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

267

268 - `type: Literal["static"]`

269

270 Always `static`.

271

272 - `"static"`

239 273

240- `description: Optional[str]`274- `description: Optional[str]`

241 275

443 477

444**get** `/vector_stores/{vector_store_id}`478**get** `/vector_stores/{vector_store_id}`

445 479

446Retrieve vector store480Retrieves a vector store.

447 481

448### Parameters482### Parameters

449 483

612 646

613**post** `/vector_stores/{vector_store_id}`647**post** `/vector_stores/{vector_store_id}`

614 648

615Modify vector store649Modifies a vector store.

616 650

617### Parameters651### Parameters

618 652

819 853

820**delete** `/vector_stores/{vector_store_id}`854**delete** `/vector_stores/{vector_store_id}`

821 855

822Delete vector store856Delete a vector store.

823 857

824### Parameters858### Parameters

825 859

890 924

891**post** `/vector_stores/{vector_store_id}/search`925**post** `/vector_stores/{vector_store_id}/search`

892 926

893Search vector store927Search a vector store for relevant chunks based on a query and file attributes filter.

894 928

895### Parameters929### Parameters

896 930

945 979

946 - `"nin"`980 - `"nin"`

947 981

948 - `value: Union[str, float, bool, List[object]]`982 - `value: Union[str, float, bool, List[Union[str, float]]]`

949 983

950 The value to compare against the attribute key; supports string, number, or boolean types.984 The value to compare against the attribute key; supports string, number, or boolean types.

951 985

955 989

956 - `bool`990 - `bool`

957 991

958 - `List[object]`992 - `List[Union[str, float]]`

993

994 - `str`

995

996 - `float`

959 997

960 - `class CompoundFilter: …`998 - `class CompoundFilter: …`

961 999

1109 1147

1110### File Chunking Strategy1148### File Chunking Strategy

1111 1149

1112- `object`1150- `FileChunkingStrategy`

1151

1152 The strategy used to chunk the file.

1153

1154 - `class StaticFileChunkingStrategyObject: …`

1155

1156 - `static: StaticFileChunkingStrategy`

1157

1158 - `chunk_overlap_tokens: int`

1159

1160 The number of tokens that overlap between chunks. The default value is `400`.

1161

1162 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1163

1164 - `max_chunk_size_tokens: int`

1165

1166 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1167

1168 - `type: Literal["static"]`

1169

1170 Always `static`.

1171

1172 - `"static"`

1173

1174 - `class OtherFileChunkingStrategyObject: …`

1175

1176 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.

1177

1178 - `type: Literal["other"]`

1179

1180 Always `other`.

1181

1182 - `"other"`

1113 1183

1114### File Chunking Strategy Param1184### File Chunking Strategy Param

1115 1185

1116- `object`1186- `FileChunkingStrategyParam`

1187

1188 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.

1189

1190 - `class AutoFileChunkingStrategyParam: …`

1191

1192 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.

1193

1194 - `type: Literal["auto"]`

1195

1196 Always `auto`.

1197

1198 - `"auto"`

1199

1200 - `class StaticFileChunkingStrategyObjectParam: …`

1201

1202 Customize your own chunking strategy by setting chunk size and chunk overlap.

1203

1204 - `static: StaticFileChunkingStrategy`

1205

1206 - `chunk_overlap_tokens: int`

1207

1208 The number of tokens that overlap between chunks. The default value is `400`.

1209

1210 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1211

1212 - `max_chunk_size_tokens: int`

1213

1214 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1215

1216 - `type: Literal["static"]`

1217

1218 Always `static`.

1219

1220 - `"static"`

1117 1221

1118### Other File Chunking Strategy Object1222### Other File Chunking Strategy Object

1119 1223

1342 1446

1343**get** `/vector_stores/{vector_store_id}/files`1447**get** `/vector_stores/{vector_store_id}/files`

1344 1448

1345List vector store files1449Returns a list of vector store files.

1346 1450

1347### Parameters1451### Parameters

1348 1452

1452 1556

1453 - `bool`1557 - `bool`

1454 1558

1455 - `chunking_strategy: Optional[object]`1559 - `chunking_strategy: Optional[FileChunkingStrategy]`

1560

1561 The strategy used to chunk the file.

1562

1563 - `class StaticFileChunkingStrategyObject: …`

1564

1565 - `static: StaticFileChunkingStrategy`

1566

1567 - `chunk_overlap_tokens: int`

1568

1569 The number of tokens that overlap between chunks. The default value is `400`.

1570

1571 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1572

1573 - `max_chunk_size_tokens: int`

1574

1575 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1576

1577 - `type: Literal["static"]`

1578

1579 Always `static`.

1580

1581 - `"static"`

1582

1583 - `class OtherFileChunkingStrategyObject: …`

1584

1585 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.

1586

1587 - `type: Literal["other"]`

1588

1589 Always `other`.

1590

1591 - `"other"`

1456 1592

1457### Example1593### Example

1458 1594

1489 "attributes": {1625 "attributes": {

1490 "foo": "string"1626 "foo": "string"

1491 },1627 },

1492 "chunking_strategy": {}1628 "chunking_strategy": {

1629 "static": {

1630 "chunk_overlap_tokens": 0,

1631 "max_chunk_size_tokens": 100

1632 },

1633 "type": "static"

1634 }

1493 }1635 }

1494 ],1636 ],

1495 "first_id": "file-abc123",1637 "first_id": "file-abc123",

1542 1684

1543**post** `/vector_stores/{vector_store_id}/files`1685**post** `/vector_stores/{vector_store_id}/files`

1544 1686

1545Create vector store file1687Create a vector store file by attaching a [File](https://platform.openai.com/docs/api-reference/files) to a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object).

1546 1688

1547### Parameters1689### Parameters

1548 1690

1566 1708

1567 - `bool`1709 - `bool`

1568 1710

1569- `chunking_strategy: Optional[object]`1711- `chunking_strategy: Optional[FileChunkingStrategyParam]`

1712

1713 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.

1714

1715 - `class AutoFileChunkingStrategyParam: …`

1716

1717 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.

1718

1719 - `type: Literal["auto"]`

1720

1721 Always `auto`.

1722

1723 - `"auto"`

1724

1725 - `class StaticFileChunkingStrategyObjectParam: …`

1726

1727 Customize your own chunking strategy by setting chunk size and chunk overlap.

1728

1729 - `static: StaticFileChunkingStrategy`

1730

1731 - `chunk_overlap_tokens: int`

1732

1733 The number of tokens that overlap between chunks. The default value is `400`.

1734

1735 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1736

1737 - `max_chunk_size_tokens: int`

1738

1739 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1740

1741 - `type: Literal["static"]`

1742

1743 Always `static`.

1744

1745 - `"static"`

1570 1746

1571### Returns1747### Returns

1572 1748

1640 1816

1641 - `bool`1817 - `bool`

1642 1818

1643 - `chunking_strategy: Optional[object]`1819 - `chunking_strategy: Optional[FileChunkingStrategy]`

1820

1821 The strategy used to chunk the file.

1822

1823 - `class StaticFileChunkingStrategyObject: …`

1824

1825 - `static: StaticFileChunkingStrategy`

1826

1827 - `chunk_overlap_tokens: int`

1828

1829 The number of tokens that overlap between chunks. The default value is `400`.

1830

1831 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

1832

1833 - `max_chunk_size_tokens: int`

1834

1835 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

1836

1837 - `type: Literal["static"]`

1838

1839 Always `static`.

1840

1841 - `"static"`

1842

1843 - `class OtherFileChunkingStrategyObject: …`

1844

1845 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.

1846

1847 - `type: Literal["other"]`

1848

1849 Always `other`.

1850

1851 - `"other"`

1644 1852

1645### Example1853### Example

1646 1854

1675 "attributes": {1883 "attributes": {

1676 "foo": "string"1884 "foo": "string"

1677 },1885 },

1678 "chunking_strategy": {}1886 "chunking_strategy": {

1887 "static": {

1888 "chunk_overlap_tokens": 0,

1889 "max_chunk_size_tokens": 100

1890 },

1891 "type": "static"

1892 }

1679}1893}

1680```1894```

1681 1895

1712 1926

1713**post** `/vector_stores/{vector_store_id}/files/{file_id}`1927**post** `/vector_stores/{vector_store_id}/files/{file_id}`

1714 1928

1715Update vector store file attributes1929Update attributes on a vector store file.

1716 1930

1717### Parameters1931### Parameters

1718 1932

1806 2020

1807 - `bool`2021 - `bool`

1808 2022

1809 - `chunking_strategy: Optional[object]`2023 - `chunking_strategy: Optional[FileChunkingStrategy]`

2024

2025 The strategy used to chunk the file.

2026

2027 - `class StaticFileChunkingStrategyObject: …`

2028

2029 - `static: StaticFileChunkingStrategy`

2030

2031 - `chunk_overlap_tokens: int`

2032

2033 The number of tokens that overlap between chunks. The default value is `400`.

2034

2035 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

2036

2037 - `max_chunk_size_tokens: int`

2038

2039 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

2040

2041 - `type: Literal["static"]`

2042

2043 Always `static`.

2044

2045 - `"static"`

2046

2047 - `class OtherFileChunkingStrategyObject: …`

2048

2049 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.

2050

2051 - `type: Literal["other"]`

2052

2053 Always `other`.

2054

2055 - `"other"`

1810 2056

1811### Example2057### Example

1812 2058

1844 "attributes": {2090 "attributes": {

1845 "foo": "string"2091 "foo": "string"

1846 },2092 },

1847 "chunking_strategy": {}2093 "chunking_strategy": {

2094 "static": {

2095 "chunk_overlap_tokens": 0,

2096 "max_chunk_size_tokens": 100

2097 },

2098 "type": "static"

2099 }

1848}2100}

1849```2101```

1850 2102

1854 2106

1855**get** `/vector_stores/{vector_store_id}/files/{file_id}`2107**get** `/vector_stores/{vector_store_id}/files/{file_id}`

1856 2108

1857Retrieve vector store file2109Retrieves a vector store file.

1858 2110

1859### Parameters2111### Parameters

1860 2112

1934 2186

1935 - `bool`2187 - `bool`

1936 2188

1937 - `chunking_strategy: Optional[object]`2189 - `chunking_strategy: Optional[FileChunkingStrategy]`

2190

2191 The strategy used to chunk the file.

2192

2193 - `class StaticFileChunkingStrategyObject: …`

2194

2195 - `static: StaticFileChunkingStrategy`

2196

2197 - `chunk_overlap_tokens: int`

2198

2199 The number of tokens that overlap between chunks. The default value is `400`.

2200

2201 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

2202

2203 - `max_chunk_size_tokens: int`

2204

2205 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

2206

2207 - `type: Literal["static"]`

2208

2209 Always `static`.

2210

2211 - `"static"`

2212

2213 - `class OtherFileChunkingStrategyObject: …`

2214

2215 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.

2216

2217 - `type: Literal["other"]`

2218

2219 Always `other`.

2220

2221 - `"other"`

1938 2222

1939### Example2223### Example

1940 2224

1969 "attributes": {2253 "attributes": {

1970 "foo": "string"2254 "foo": "string"

1971 },2255 },

1972 "chunking_strategy": {}2256 "chunking_strategy": {

2257 "static": {

2258 "chunk_overlap_tokens": 0,

2259 "max_chunk_size_tokens": 100

2260 },

2261 "type": "static"

2262 }

1973}2263}

1974```2264```

1975 2265

2005 2295

2006**delete** `/vector_stores/{vector_store_id}/files/{file_id}`2296**delete** `/vector_stores/{vector_store_id}/files/{file_id}`

2007 2297

2008Delete vector store file2298Delete a vector store file. This will remove the file from the vector store but the file itself will not be deleted. To delete the file, use the [delete file](https://platform.openai.com/docs/api-reference/files/delete) endpoint.

2009 2299

2010### Parameters2300### Parameters

2011 2301

2080 2370

2081**get** `/vector_stores/{vector_store_id}/files/{file_id}/content`2371**get** `/vector_stores/{vector_store_id}/files/{file_id}/content`

2082 2372

2083Retrieve vector store file content2373Retrieve the parsed contents of a vector store file.

2084 2374

2085### Parameters2375### Parameters

2086 2376

2207 2497

2208 - `bool`2498 - `bool`

2209 2499

2210 - `chunking_strategy: Optional[object]`2500 - `chunking_strategy: Optional[FileChunkingStrategy]`

2501

2502 The strategy used to chunk the file.

2503

2504 - `class StaticFileChunkingStrategyObject: …`

2505

2506 - `static: StaticFileChunkingStrategy`

2507

2508 - `chunk_overlap_tokens: int`

2509

2510 The number of tokens that overlap between chunks. The default value is `400`.

2511

2512 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

2513

2514 - `max_chunk_size_tokens: int`

2515

2516 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

2517

2518 - `type: Literal["static"]`

2519

2520 Always `static`.

2521

2522 - `"static"`

2523

2524 - `class OtherFileChunkingStrategyObject: …`

2525

2526 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.

2527

2528 - `type: Literal["other"]`

2529

2530 Always `other`.

2531

2532 - `"other"`

2211 2533

2212### Vector Store File Deleted2534### Vector Store File Deleted

2213 2535

2241 2563

2242**post** `/vector_stores/{vector_store_id}/file_batches`2564**post** `/vector_stores/{vector_store_id}/file_batches`

2243 2565

2244Create vector store file batch2566Create a vector store file batch.

2245 2567

2246### Parameters2568### Parameters

2247 2569

2261 2583

2262 - `bool`2584 - `bool`

2263 2585

2264- `chunking_strategy: Optional[object]`2586- `chunking_strategy: Optional[FileChunkingStrategyParam]`

2587

2588 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.

2589

2590 - `class AutoFileChunkingStrategyParam: …`

2591

2592 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.

2593

2594 - `type: Literal["auto"]`

2595

2596 Always `auto`.

2597

2598 - `"auto"`

2599

2600 - `class StaticFileChunkingStrategyObjectParam: …`

2601

2602 Customize your own chunking strategy by setting chunk size and chunk overlap.

2603

2604 - `static: StaticFileChunkingStrategy`

2605

2606 - `chunk_overlap_tokens: int`

2607

2608 The number of tokens that overlap between chunks. The default value is `400`.

2609

2610 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

2611

2612 - `max_chunk_size_tokens: int`

2613

2614 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

2615

2616 - `type: Literal["static"]`

2617

2618 Always `static`.

2619

2620 - `"static"`

2265 2621

2266- `file_ids: Optional[Sequence[str]]`2622- `file_ids: Optional[Sequence[str]]`

2267 2623

2289 2645

2290 - `bool`2646 - `bool`

2291 2647

2292 - `chunking_strategy: Optional[object]`2648 - `chunking_strategy: Optional[FileChunkingStrategyParam]`

2649

2650 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.

2293 2651

2294### Returns2652### Returns

2295 2653

2434 2792

2435**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}`2793**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}`

2436 2794

2437Retrieve vector store file batch2795Retrieves a vector store file batch.

2438 2796

2439### Parameters2797### Parameters

2440 2798

2573 2931

2574**post** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`2932**post** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`

2575 2933

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

2577 2935

2578### Parameters2936### Parameters

2579 2937

2712 3070

2713**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`3071**get** `/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`

2714 3072

2715List vector store files in a batch3073Returns a list of vector store files in a batch.

2716 3074

2717### Parameters3075### Parameters

2718 3076

2824 3182

2825 - `bool`3183 - `bool`

2826 3184

2827 - `chunking_strategy: Optional[object]`3185 - `chunking_strategy: Optional[FileChunkingStrategy]`

3186

3187 The strategy used to chunk the file.

3188

3189 - `class StaticFileChunkingStrategyObject: …`

3190

3191 - `static: StaticFileChunkingStrategy`

3192

3193 - `chunk_overlap_tokens: int`

3194

3195 The number of tokens that overlap between chunks. The default value is `400`.

3196

3197 Note that the overlap must not exceed half of `max_chunk_size_tokens`.

3198

3199 - `max_chunk_size_tokens: int`

3200

3201 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.

3202

3203 - `type: Literal["static"]`

3204

3205 Always `static`.

3206

3207 - `"static"`

3208

3209 - `class OtherFileChunkingStrategyObject: …`

3210

3211 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.

3212

3213 - `type: Literal["other"]`

3214

3215 Always `other`.

3216

3217 - `"other"`

2828 3218

2829### Example3219### Example

2830 3220

2862 "attributes": {3252 "attributes": {

2863 "foo": "string"3253 "foo": "string"

2864 },3254 },

2865 "chunking_strategy": {}3255 "chunking_strategy": {

3256 "static": {

3257 "chunk_overlap_tokens": 0,

3258 "max_chunk_size_tokens": 100

3259 },

3260 "type": "static"

3261 }

2866 }3262 }

2867 ],3263 ],

2868 "first_id": "file-abc123",3264 "first_id": "file-abc123",

python/resources/vector_stores/index.md 2026-07-10 23:02 UTC to 2026-07-12 06:58 UTC

Vector Stores

List vector stores

Parameters

Returns

Example

Response

Example

Response

Create vector store

Parameters

Returns

Example

Response

Example

Response

Retrieve vector store

Parameters

Returns

Example

Response

Example

Response

Modify vector store

Parameters

Returns

Example

Response

Example

Response

Delete vector store

Parameters

Returns

Example

Response

Example

Response

Search vector store

Parameters

Returns

Example

Response

Domain Types

Auto File Chunking Strategy Param

File Chunking Strategy

File Chunking Strategy Param

Other File Chunking Strategy Object

Static File Chunking Strategy

Static File Chunking Strategy Object

Static File Chunking Strategy Object Param

Vector Store

Vector Store Deleted

Vector Store Search Response

Files

List vector store files

Parameters

Returns

Example

Response

Example

Response

Create vector store file

Parameters

Returns

Example

Response

Example

Response

Update vector store file attributes

Parameters

Returns

Example

Response

Retrieve vector store file

Parameters

Returns

Example

Response

Example

Response