Set keyword, semantic, or hybrid retrieval on collection search

POST https://api.x.ai/v1/documents/search (regular XAI_API_KEY) can pick how chunks are retrieved. Default is hybrid. Agent-style chat search with file_search / collections_search is covered in Search collections with the Grok API. This page is the direct documents search call and its retrieval_mode.

Modes

Mode	Best for	Tradeoff
keyword	Exact terms (account ids, dates, figures)	Misses paraphrases
semantic	Meaning / topic when wording differs	Weaker on precise literals
hybrid	Most real queries (default)	Slightly higher latency

Call with retrieval_mode

curl https://api.x.ai/v1/documents/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "query": "What is the revenue in the last quarter?",
    "source": {
      "collection_ids": ["collection_80100614-300c-4609-959b-a138fa90f542"]
    },
    "retrieval_mode": {"type": "hybrid"},
    "limit": 10
  }'

Swap "type" to "keyword" or "semantic" when you need those behaviors. Optional filter uses AIP-160 metadata syntax — see Set collection metadata fields and filter search.

Response matches include chunk_content, file_id, score, and document fields.

When to leave hybrid alone

Keep hybrid unless you already know the query is a precise identifier hunt (keyword) or a broad topical dig with no stable terms (semantic). Hybrid is the documented default for most workloads.

Pitfalls

• Filtering on metadata keys that were never defined on the collection — empty matches.
• Expecting wildcard filters (author="E*") — not supported; string compares are exact.
• Using a Management API key on api.x.ai document search — this endpoint wants the inference XAI_API_KEY.