File search (type: "file_search") — tool side
Status: DOCUMENTED · LIVE_VERIFIED (2026-09-18, gpt-5.4-nano, vector store atlas-tools-agent created and deleted). Vector store CRUD itself is documented by the vector-stores fragment.
Sources: https://developers.openai.com/api/docs/guides/tools-file-search · https://developers.openai.com/api/docs/pricing#built-in-tools · openapi-master.yaml FileSearchTool, RankingOptions, HybridSearchOptions, ComparisonFilter, CompoundFilter, FileSearchToolCall
Last verified: 2026-09-18
Parameters
| Parameter | Type / enum | Req. | Notes |
|---|---|---|---|
type |
file_search |
yes | |
vector_store_ids |
string[] | yes | deep research models accept only type + vector_store_ids |
max_num_results |
integer 1–50 | no | fewer results = fewer tokens |
ranking_options.ranker |
auto | default-2024-11-15 |
no | |
ranking_options.score_threshold |
number 0–1 | no | |
ranking_options.hybrid_search |
{embedding_weight, text_weight} (both required) |
no | reciprocal rank fusion weights |
filters |
ComparisonFilter {type: eq|ne|gt|gte|lt|lte|in|nin, key, value} | CompoundFilter {type: and|or, filters[]} |
no | on file attributes |
include: ["file_search_call.results"] returns the retrieved chunks (hidden by default).
Output
file_search_call {id:"fs_…", type, status: in_progress|searching|completed|incomplete|failed, queries[], results[]|null}; results[] = {file_id, filename, score, text, attributes, vector_store_id}. Message annotations: file_citation {file_id, filename, index}.
Streaming (live)
response.output_item.added → response.file_search_call.in_progress → response.file_search_call.searching → response.file_search_call.completed → response.output_item.done → text events.
Billing (cited)
$2.50 / 1k tool calls; storage $0.10 / GB / day after 1 GB free.
Live evidence
| Probe | Status | Result |
|---|---|---|
max_output_tokens: 32 |
200 | response incomplete, file_search_call.status: "incomplete" (budget too small for reasoning + search) |
max_output_tokens: 300 (stream) |
200 | queries: ["What is the secret codeword?", "secret codeword", "codeword"] (model rewrites), results[0].score 0.7626–0.83, results[0].vector_store_id: "" (empty string, spec says id), annotations: [] in the answer, text PELICAN-42; usage 2083 in / 59 out |
| sh/py/ts examples | 200 | identical shapes; sh needed direct curl -F for the file upload (the oai helper forces JSON content type) |
Security: retrieved chunks are model input — upload trusted files only. Examples: examples/openai/tools/file-search/. Test (expensive): test_file_search_roundtrip.