Search collections with the Grok API

file_search lets Grok query documents you already uploaded into a collection. Create the collection and wait until each file is processed, then pass the collection id on POST https://api.x.ai/v1/responses. Get a key at console.x.ai.

Create, then search

Upload through the xAI SDK (client.collections.create, upload_document) or the console. Poll until the document status is processed. Then:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.6",
  "input": [
    {
      "role": "user",
      "content": "How many consumer vehicles did Tesla produce in 2024? Cite the filings."
    }
  ],
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["your_collection_id_here"],
      "max_num_results": 10
    }
  ]
}'

Python with the official SDK:

import os
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import collections_search, code_execution

client = Client(api_key=os.getenv("XAI_API_KEY"))
collection_id = "your_collection_id_here"
chat = client.chat.create(
    model="grok-4.6",
    tools=[
        collections_search(collection_ids=[collection_id]),
        code_execution(),
    ],
)
chat.append(user("How many consumer vehicles did Tesla produce in 2024? Cite the filings."))
for response, chunk in chat.stream():
    if chunk.content:
        print(chunk.content, end="", flush=True)
print("\nCitations:", response.citations)

xAI SDK: collections_search(collection_ids=[...]). Responses API: type: "file_search" with vector_store_ids. Collection ids from console.x.ai or client.collections.create drop straight into that field.

Citations

Hits come back as collections://collection_id/files/file_id. Open those if you need the exact page. Grok will run several searches on one question. Pair file_search with code_interpreter when you want it to add the numbers it found.

Pitfalls

• Searching an empty or still-processing collection returns nothing useful. Wait for DOCUMENT_STATUS_PROCESSED.
• max_num_results caps how many chunks come back per call. Raise it for long filings.
• Management calls (create, upload) use the management key. Chat search uses the regular API key.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.