collections_search and file_search in the Responses API

Integrate search directly into conversations

The POST /v1/documents/search endpoint works well for isolated questions, but it leaves all the orchestration work to you: formulating the query, retrieving excerpts, injecting them into a prompt, and calling the model. The Responses API flips this burden. By declaring your collections as a tool, you let Grok decide when to search, what to look for, and how to turn it into an answer. You move from a pipeline you drive to an assistant that searches your documents itself.

The collections_search tool

You just need to add an object to the tools list to enable this access:

response = await client.responses.create(
    model="grok-4.5",
    input="What is our paternity leave policy?",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_rh_policies"]
        }
    ]
)

Behind this single call, Grok analyzes the question, formulates a search query tailored to the collection, retrieves relevant passages, summarizes them, and cites the documents used. In practice, for the question above, it will translate “paternity leave” into a search in col_rh_policies, retain the paragraphs from the company agreement, and return a number of days along with its source, without you writing a single line of retrieval logic.

The file_search tool

The counterpart exists for individual files, those not stored in a collection. No need to declare it: it activates automatically as soon as your request contains an input_file.

response = await client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_file",
            "file_id": "file_contrat_abc"
        },
        {
            "type": "input_text",
            "text": "Does this contract contain a non-compete clause?"
        }
    ]
)

It’s the attachment_search tool, equivalent to file_search, that activates in the background. This implicit behavior explains a common confusion: users wonder why declaring file_search in tools seems to have no effect, when it’s simply redundant.

Two mechanisms, two cost structures

The “indexing” line drives all the others. A collection is indexed once and for all, so every question reuses that work: it’s fast and billed at $2.50 per thousand calls. An attached file is indexed with every request, hence the additional latency and the $10 per thousand. The contract your legal counsel analyzes once falls into the second category; the HR repository queried a hundred times a day obviously falls into the first.

Combine multiple tools

The real benefit of this approach appears when you give Grok several of them, letting it select the ones that serve the question.

response = await client.responses.create(
    model="grok-4.5",
    input="Compare our internal policy with the latest European regulations on the subject.",
    tools=[
        {
            "type": "collections_search",
            "collection_ids": ["col_politiques_internes"]
        },
        {
            "type": "web_search"
        }
    ]
)

This question calls for two successive moves: Grok first queries the collection to find your internal policy, then launches a web search for current European regulations, then contrasts the two in its response. No orchestration on your side, no if statement to decide which of the two sources is relevant—and if the question had focused solely on your internal policy, the web would not have been used.

Refine tool behavior

Three parameters let you tighten the search declared in tools.

tools=[
    {
        "type": "collections_search",
        "collection_ids": ["col_docs_1", "col_docs_2"],
        "max_results": 10,
        "retrieval_mode": "hybrid"
    }
]

• collection_ids: query multiple collections simultaneously
• max_results: limit the number of results to reduce injected context
• retrieval_mode: choose the search mode (hybrid by default)

max_results deserves special attention: every excerpt returned takes up context and costs tokens. On a support assistant where responses generally fit within two or three passages, dropping from the default value to five results reduces the cost without degrading perceived quality.

Pricing as of August 5, 2026 — prices change regularly: before calculating any budget, check the current pricing on the official xAI models and pricing page.

Key takeaways

• collections_search lets Grok automatically query your collections during a conversation
• file_search / attachment_search activates automatically for individual files
• Collections are four times cheaper and faster than file attachments
• You can combine collections_search with web_search and other tools
• Grok automatically chooses which tools to use based on the question