# Gemini — File Search (tools[].fileSearch + fileSearchStores API, Preview)

Status: DOCUMENTED + LIVE_VERIFIED (2026-09-18 run — see "Live verification" section at the end)

Sources:

• https://ai.google.dev/gemini-api/docs/generate-content/file-search · https://ai.google.dev/gemini-api/docs/file-search
• https://ai.google.dev/api/file-search/file-search-stores · https://ai.google.dev/api/file-search/documents · https://ai.google.dev/api/all-methods
• https://ai.google.dev/api/generate-content (#FileSearch #RetrievedContext #CustomMetadata) · https://ai.google.dev/gemini-api/docs/pricing · changelog (public preview 2025-11; multimodal 2026-02)
• Discovery v1beta rev. 20260918: resources fileSearchStores, media.uploadToFileSearchStore

Last verified: 2026-09-18 (docs only)

# 1. Concepts and lifecycle

 file bytes ──uploadToFileSearchStore (LRO)──▶ FileSearchStore ──▶ Document ──▶ Chunks + embeddings
 Files API File (48 h) ──importFile (LRO)────▶      │
                                                     └── generateContent tools[].fileSearch ──▶ groundingMetadata.retrievedContext

• FileSearchStore: persistent container (no TTL; deleted only by you or model deprecation). Names are globally scoped, server-generated: fileSearchStores/<displayName-slug>-<12 random chars>.
• Document: one ingested file; state STATE_PENDING → STATE_ACTIVE | STATE_FAILED; up to 20 customMetadata.
• Embedding model fixed at store creation: default text model (gemini-embedding-001 per guide) or models/gemini-embedding-2 for multimodal (PNG/JPEG ≤ 4K×4K).
• Semantic search at query time; retrieved chunks are injected as context and cited in groundingMetadata.

# 2. Endpoints

Delete semantics: force=false (default) → FAILED_PRECONDITION if the store has Documents / the Document has Chunks; force=true cascades.

# 3. Upload protocols (REST)

Resumable (guide example): POST https://generativelanguage.googleapis.com/upload/v1beta/fileSearchStores/{id}:uploadToFileSearchStore with headers X-Goog-Upload-Protocol: resumable, X-Goog-Upload-Command: start, X-Goog-Upload-Header-Content-Length: <bytes>, X-Goog-Upload-Header-Content-Type: <mime>, JSON body {"displayName":"sample.txt"} → read X-Goog-Upload-URL from response headers → POST <upload url> with X-Goog-Upload-Offset: 0, X-Goog-Upload-Command: upload, finalize, --data-binary @file → Operation JSON. Simple/multipart: multipart/related body on the same /upload/v1beta/ URI (discovery mediaUpload.protocols.simple.multipart: true). Poll GET /v1beta/<operation.name> until done: true.

# 4. Chunking, metadata, filters

# 5. Query response

"groundingMetadata": {
  "groundingChunks": [{"retrievedContext": {"title": "sample.txt", "uri": "...", "text": "chunk text",
      "fileSearchStore": "fileSearchStores/my-store-123", "pageNumber": 3,
      "mediaId": "fileSearchStores/my-store-123/media/BlobId-456",
      "customMetadata": [{"key": "author", "stringValue": "Robert Graves"}, {"key": "year", "numericValue": 1934}]}}],
  "groundingSupports": [{"segment": {"startIndex": 0, "endIndex": 50, "text": "..."}, "groundingChunkIndices": [0]}]
}

pageNumber for paged documents (PDF); mediaId for image chunks (persistent across searches). With includeServerSideToolInvocations: toolCall{toolType: FILE_SEARCH} (no user-visible args). Structured outputs + File Search: Gemini 3.

# 6. Supported file types (summary)

Application: dart, ecmascript, json, ms-java, msword, pdf, sql, typescript, vnd.curl, vnd.dart, vnd.ibm.secure-container, vnd.jupyter, vnd.ms-excel, vnd.oasis.opendocument.text, OOXML pptx/xlsx/docx/dotx, x-csh, x-hwp(-v5), x-latex, x-php, x-powershell, x-sh, x-shellscript, x-tex, x-zsh, xml, zip. Text: ~150 text/* types incl. plain, html, css, csv, tsv, markdown, javascript, jsx, tsx, x-python, x-java, x-c, x-go, x-rust, yaml, xml… (full list in the guide). Images (PNG, JPEG) only with models/gemini-embedding-2. Audio and video not supported.

# 7. Limits and tiers

# 8. Pricing

# 9. Supported models

Guide table: gemini-3.8/3.7/3.6/3.5-flash, 3.5-flash-lite, 3.1-pro-preview, 3.1-flash-lite, 3-flash-preview, 2.5-pro, 2.5-flash-lite. Model pages add gemini-2.5-flash, gemini-3-pro-preview, 3.1-flash-lite-preview, robotics ER 2; gemini-3.1-pro-preview page says "Supported (AI Studio only)".

# 10. Examples

# create store
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores" \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
  -d '{"displayName":"atlas-test","embeddingModel":"models/gemini-embedding-2"}'
# query
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"What is in the uploaded file?"}]}],
       "tools":[{"fileSearch":{"fileSearchStoreNames":["fileSearchStores/STORE_ID"],"metadataFilter":"author = \"X\""}}]}'

store = client.file_search_stores.create(config={"display_name": "atlas-test"})
op = client.file_search_stores.upload_to_file_search_store(file="sample.txt", file_search_store_name=store.name,
        config={"display_name": "sample.txt", "custom_metadata": [{"key": "author", "string_value": "X"}]})
while not op.done: time.sleep(3); op = client.operations.get(op)
r = client.models.generate_content(model="gemini-3.5-flash-lite", contents="What is in the file?",
        config=types.GenerateContentConfig(tools=[types.Tool(file_search=types.FileSearch(file_search_store_names=[store.name]))]))
print(r.candidates[0].grounding_metadata.grounding_chunks)
client.file_search_stores.delete(name=store.name, config={"force": True})

const store = await ai.fileSearchStores.create({ config: { displayName: 'atlas-test' } });
let op = await ai.fileSearchStores.uploadToFileSearchStore({ file: 'sample.txt', fileSearchStoreName: store.name, config: { displayName: 'sample.txt' } });
while (!op.done) op = await ai.operations.get({ operation: op });
const r = await ai.models.generateContent({ model: 'gemini-3.5-flash-lite', contents: 'What is in the file?',
  config: { tools: [{ fileSearch: { fileSearchStoreNames: [store.name] } }] } });
await ai.fileSearchStores.delete({ name: store.name, config: { force: true } });

# Live verification (2026-09-18)

LIVE_VERIFIED end-to-end (tmp-live/gemini-tools/g*.json, examples/gemini/file-search/file_search_lifecycle.py, file_search.ts, tests/gemini/test_file_search.py):

Not exercised: importFile, /operations/{op} poller for imports, media/{blob} download.