How to beginner · 3 min read

How to use file search with Responses API

Q: How to use file search with Responses API

Use the OpenAI SDK's responses.search method to perform file search by specifying the file ID and a query. This returns relevant document matches from the uploaded file. Authenticate with your API key and provide the file ID to search within.

Quick answer

Use the OpenAI SDK's responses.search method to perform file search by specifying the file ID and a query. This returns relevant document matches from the uploaded file. Authenticate with your API key and provide the file ID to search within.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0

Setup

Install the official openai Python package (v1+) and set your API key as an environment variable.

Install package: pip install openai
Set environment variable: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install openai

Step by step

This example demonstrates how to search an uploaded file using the responses.search endpoint. Replace file_id with your actual file ID obtained after uploading your documents.

python

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Replace with your uploaded file ID
file_id = "file-xxxxxxxxxxxxxxxxxxxx"

query = "Find information about AI models"

response = client.responses.search(
    file=file_id,
    query=query,
    max_rerank=10  # Optional: number of top matches to return
)

for match in response.data:
    print(f"Score: {match.score:.4f}")
    print(f"Text snippet: {match.text}\n")

output

Score: 0.9876
Text snippet: GPT-4o is a powerful AI model designed for chat and code generation.

Score: 0.8765
Text snippet: File search allows you to retrieve relevant document sections efficiently.

Common variations

You can customize your file search by:

Adjusting max_rerank to control how many top results are returned.
Using different query strings for varied search intents.
Performing asynchronous calls with asyncio for high throughput.
Searching multiple files by calling responses.search separately for each file.

python

import asyncio
import os
from openai import OpenAI

async def async_file_search(file_id: str, query: str):
    client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    response = await client.responses.search(
        file=file_id,
        query=query,
        max_rerank=5
    )
    for match in response.data:
        print(f"Score: {match.score:.4f}")
        print(f"Text snippet: {match.text}\n")

if __name__ == "__main__":
    file_id = "file-xxxxxxxxxxxxxxxxxxxx"
    query = "Explain retrieval augmented generation"
    asyncio.run(async_file_search(file_id, query))

output

Score: 0.9543
Text snippet: Retrieval augmented generation (RAG) combines search with generation to improve accuracy.

Troubleshooting

File not found error: Ensure your file_id is correct and the file is uploaded successfully.
Empty results: Try refining your query or increase max_rerank to get more matches.
Authentication errors: Verify your OPENAI_API_KEY environment variable is set and valid.
API version mismatch: Use the latest openai SDK (v1+) to avoid deprecated endpoints.

✅

Key Takeaways

Use client.responses.search with your file ID and query to retrieve relevant document snippets.
Adjust max_rerank to control the number of search results returned.
Always authenticate with your API key via os.environ and use the latest openai SDK.
For high throughput, use asynchronous calls with asyncio.
Verify your file is uploaded and accessible before performing searches.

Verified 2026-04

Verify ↗