OpenAI file search and vector stores: how the tool works

File search is a hosted tool in OpenAI's Responses API that lets a model retrieve information from a knowledge base of uploaded files using semantic and keyword search. You upload files, add them to a vector store, then reference the store in a request. OpenAI manages execution.

The setup flow

Per the documentation:

1. Upload the file with the File API.
2. Create a vector store, which serves as the knowledge base.
3. Add the file to the store.
4. Check its status until it reads completed.

Then add a file search tool to the request and list the vector store IDs. The response contains a file search call item and a message with file citation annotations pointing to source files.

Getting the results back

Search results are not returned by default. To see them, set the include option to request the file search call results. This is useful when you want to check what was retrieved rather than trust the answer.

Tuning

• A maximum number of results setting limits retrieval. It can cut token use and latency but may lower answer quality.
• Metadata filters narrow results by file attributes, such as a category value. The page defers to the retrieval guide for attribute setup.

Supported files

Common formats include PDF, DOCX, PPTX, DOC, Markdown, plain text, HTML, JSON and many source code files in languages such as Python, JavaScript, Java and Go. For text MIME types, the encoding must be utf-8, utf-16 or ascii.

Limits and what is unstated

Rate limits are 500 requests per minute on the Build tier and 1000 on Launch and Grow. The page does not state file size or file count limits, and it gives no specific pricing, pointing to the pricing page for built-in tools. Check both before planning a large index.

Security angles

Whatever you index can reach the model, so index only what the app's users may see. Metadata filters help, but do not treat them as a replacement for per-user access control in your application. Retrieved text can also contain instructions aimed at the model, which is the core RAG injection risk.

If you are weighing retrieval against training your own model, start with how retrieval works, then read Claude Projects explained for a consumer version of the same idea.

Safeguard offers a free scan at gold.safeguard.sh/scan.

Checking quality

Before you ship, ask a set of questions where you already know the answer and read the returned results, not just the final text. Look for the right file being cited, for answers that ignore a relevant file, and for results that should have been filtered out by metadata. Adjust the maximum results setting and your file contents, and test again.

Quick check

Sources

• File search (OpenAI API documentation)

Last reviewed: 19 October 2026.