Search results
Enable natural citations for RAG applications by providing search results with source attribution
Search result content blocks are currently in beta. Use the search-results-2025-06-09
beta header to enable this feature.
Search result content blocks enable natural citations with proper source attribution, bringing web search-quality citations to your custom applications. This feature is particularly powerful for RAG (Retrieval-Augmented Generation) applications where you need Claude to cite sources accurately.
The search results feature is available on the following models:
- Claude 3.5 Haiku (
claude-3-5-haiku-20241022
) - Claude 3.5 Sonnet (
claude-3-5-sonnet-20241022
) - Claude 3.7 Sonnet (
claude-3-7-sonnet-20250219
) - Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
)
Key benefits
- Natural citations - Achieve the same citation quality as web search for any content
- Flexible integration - Use in tool returns for dynamic RAG or as top-level content for pre-fetched data
- Proper source attribution - Each result includes source and title information for clear attribution
- No document workarounds needed - Eliminates the need for document-based workarounds
- Consistent citation format - Matches the citation quality and format of Claude’s web search functionality
How it works
Search results can be provided in two ways:
- From tool calls - Your custom tools return search results, enabling dynamic RAG applications
- As top-level content - You provide search results directly in user messages for pre-fetched or cached content
In both cases, Claude can automatically cite information from the search results with proper source attribution.
Search result schema
Search results use the following structure:
Required fields
Field | Type | Description |
---|---|---|
type | string | Must be "search_result" |
source | string | The source URL or identifier for the content |
title | string | A descriptive title for the search result |
content | array | An array of text blocks containing the actual content |
Optional fields
Field | Type | Description |
---|---|---|
citations | object | Citation configuration with enabled boolean field |
cache_control | object | Cache control settings (e.g., {"type": "ephemeral"} ) |
Each item in the content
array must be a text block with:
type
: Must be"text"
text
: The actual text content (non-empty string)
Method 1: Search results from tool calls
The most powerful use case is returning search results from your custom tools. This enables dynamic RAG applications where tools fetch and return relevant content with automatic citations.
Example: Knowledge base tool
Method 2: Search results as top-level content
You can also provide search results directly in user messages. This is useful for:
- Pre-fetched content from your search infrastructure
- Cached search results from previous queries
- Content from external search services
- Testing and development
Example: Direct search results
Claude’s response with citations
Regardless of how search results are provided, Claude automatically includes citations when using information from them:
Citation fields
Each citation includes:
Field | Type | Description |
---|---|---|
type | string | Always "search_result_location" for search result citations |
source | string | The source from the original search result |
title | string or null | The title from the original search result |
cited_text | string | The exact text being cited |
search_result_index | integer | Index of the search result (0-based) |
start_block_index | integer | Starting position in the content array |
end_block_index | integer | Ending position in the content array |
Note: The search_result_index
refers to the index of the search result content block (0-based), regardless of how the search results were provided (tool call or top-level content).
Multiple content blocks
Search results can contain multiple text blocks in the content
array:
Claude can cite specific blocks using the start_block_index
and end_block_index
fields.
Advanced usage
Combining both methods
You can use both tool-based and top-level search results in the same conversation:
Combining with other content types
Both methods support mixing search results with other content:
Cache control
Add cache control for better performance:
Citation control
By default, citations are disabled for search results. You can enable citations by explicitly setting the citations
configuration:
When citations.enabled
is set to true
, Claude will include citation references when using information from the search result. This enables:
- Natural citations for your custom RAG applications
- Source attribution when interfacing with proprietary knowledge bases
- Web search-quality citations for any custom tool that returns search results
If the citations
field is omitted, citations are disabled by default.
Citations are all-or-nothing: either all search results in a request must have citations enabled, or all must have them disabled. Mixing search results with different citation settings will result in an error. If you need to disable citations for some sources, you must disable them for all search results in that request.
Best practices
For tool-based search (Method 1)
- Dynamic content: Use for real-time searches and dynamic RAG applications
- Error handling: Return appropriate messages when searches fail
- Result limits: Return only the most relevant results to avoid context overflow
For top-level search (Method 2)
- Pre-fetched content: Use when you already have search results
- Batch processing: Ideal for processing multiple search results at once
- Testing: Great for testing citation behavior with known content
General best practices
-
Structure results effectively
- Use clear, permanent source URLs
- Provide descriptive titles
- Break long content into logical text blocks
-
Maintain consistency
- Use consistent source formats across your application
- Ensure titles accurately reflect content
- Keep formatting consistent
-
Handle errors gracefully
Limitations
- Search result content blocks are only available with the beta header
- Only text content is supported within search results (no images or other media)
- The
content
array must contain at least one text block