"Bring your own retrieval" (BYO retrieval) means your code does the searching — against Elasticsearch, a vector store, an internal API, whatever — and Claude does the answering. The missing piece has always been attribution: when Claude writes a paragraph, which of your retrieved chunks backs it up? The search_result content block is Anthropic's answer. The docs describe it as bringing "web search-quality citations to your custom applications," and it is aimed explicitly at retrieval-augmented generation (RAG) — the pattern where you fetch relevant documents and include them in the prompt.
The two usage modes
A search_result block can enter the conversation in two places, and you can mix both in one conversation:
Inside a tool result (dynamic RAG). You define a search tool; Claude calls it mid-conversation; your code runs the query and returns search_result blocks inside the tool_result. This suits agentic flows where Claude decides what to look up.
As top-level user content (pre-fetched retrieval). Your pipeline retrieves chunks before calling Claude and places the blocks directly in the user message. This suits classic RAG pipelines and cached or pre-computed retrieval, and the blocks can sit alongside other content types, including images.
Anatomy of a block
Each block requires a type of "search_result", a source (a URL or any identifier), a title, and content — an array of non-empty text blocks. Optional fields are citations and cache_control (so large results can be cached with prompt caching).
result = {
"type": "search_result",
"source": "https://kb.example.com/policies/travel",
"title": "Travel & Expense Policy",
"content": [
{"type": "text", "text": "Employees may book economy class..."},
{"type": "text", "text": "International trips require approval..."},
],
"citations": {"enabled": True},
}Citations are off by default — turn them on
Here is the counter-intuitive part: even though this block exists for RAG attribution, citations on search results are disabled by default. That is the opposite of the server-side web search tool, where citations are always on. The likely reason is control — you opt in per request rather than having citation formatting imposed on you. Two rules to remember:
search_result block in a request or on none of them. Mixing enabled and disabled blocks returns an error. The same all-or-nothing rule applies to citation-enabled document blocks.How the citation indexing differs from document blocks
With ordinary document-block citations, plain text documents are cited by 0-indexed character ranges (char_location) and PDFs by 1-indexed page ranges (page_location). Search results use a third scheme: the citation type is search_result_location, carrying the block's source and title, a search_result_index (0-based, counting every search_result block in the request in order), and start_block_index / end_block_index (end-exclusive) pointing into that result's content array.
The practical consequence: the text block is the minimal citable unit. Claude cites whole blocks, never substrings within them. If you dump a 2,000-word chunk into one text block, every citation will point at all 2,000 words. Split content into smaller text blocks — a paragraph or a few sentences each — for finer-grained attribution. This is the same granularity model as custom content documents; see controlling citation granularity with custom content for the trade-offs.
Model and platform support
No beta header is required. The documented model list covers the Opus 4 line (4.8 down to 4), Sonnet 5 / 4.6 / 4.5 / 4, and Haiku 4.5 and 3.5. Note that the citations page separately says all active models except Claude Haiku 3 support citations, so the search-results model list may simply be stale for the newest models — check the official page for your specific model before committing.
Platform-wise this is one of the most portable RAG features: search results blocks are GA on the Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, and Microsoft's Foundry documentation lists citations "including search_result content blocks" as a supported capability. That makes the BYO-retrieval pattern especially important on Vertex and Foundry, where the clouds' native RAG services do not document Claude as a generation model — see the Vertex RAG Engine inversion and the Foundry grounding gap.
Two more operational notes: search results content blocks are eligible for Zero Data Retention, and citation-enabled blocks cannot be combined with structured outputs (output_config.format) — that combination returns a 400 error.
Where to go next
Start with RAG basics if the retrieval side is new to you, then see the citation-grounding pattern for an end-to-end design and Voyage embeddings for the retrieval index itself.