Citations and Grounding: Making Claude, GPT, and Gemini Cite Sources
Learn how Claude, OpenAI Responses API, and Gemini handle citations and grounding: request shapes, token costs, search pricing, and implementation differences.
- Claude uses inline document blocks with chunking; cited_text does not count toward output tokens, but structured outputs cannot be enabled.
- OpenAI provides hosted retrieval via the file_search tool in the Responses API, returning file_citation annotations tied to vector stores.
- Gemini grounds via the google_search tool, offering 5,000 free queries per month across Gemini 3 and newer before charging $14 per 1,000 requests.
- Claude references text character or page ranges, OpenAI annotates file offsets, and Gemini annotates start_index and end_index linked to external URLs.
How Citation and Grounding Paradigms Differ
Grounding an LLM means anchoring its generation to verifiable facts rather than relying solely on internal model weights. However, the major API providers implement this concept differently. Anthropic embeds documents directly into the request payload or prompt cache, OpenAI offloads knowledge retrieval to hosted vector stores via a tool call, and Google executes live web searches during generation.
For teams designing document question-answering systems, these architectural differences govern latency, billing, schema flexibility, and indexing overhead. If your system passes short-to-medium documents with every call, Claude’s native document chunking requires no external infrastructure. If your system manages sprawling document repositories, OpenAI’s hosted vector storage automates chunking and similarity search. If you require current public information, Gemini connects models directly to web searches.
Anthropic Claude: In-Context Document Citations
Anthropic provides citations across all active models, such as claude-opus-5-5. Instead of executing an external search step, you pass the text or PDF directly in the messages array inside a document block with citations: {"enabled": true}. Claude segments plain text and PDFs into sentence-level chunks, while custom content documents preserve the explicit content block boundaries you provide.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "The grass is green. The sky is blue."
},
"title": "My Document",
"context": "This is a trustworthy document.",
"citations": {"enabled": true}
},
{
"type": "text",
"text": "What color is the grass and sky?"
}
]
}
]
}'
- Token economics: The returned
cited_textdoes not count toward output tokens, and returning it in later conversational turns incurs no input token billing. Input tokens increase slightly due to internal chunking and prompts. - Index referencing: Plain text uses 0-indexed character offsets with exclusive ends. PDFs report 1-indexed page ranges with exclusive ends. Document indices are 0-indexed across all message blocks.
- Prompt caching: You can pair citations with prompt caching by applying
cache_control: {"type": "ephemeral"}to the top-level document block. Learn more about caching strategies at /posts/prompt-caching-explained-claude-gpt-gemini/. - Hard limit: Citations and structured outputs cannot be combined. Setting
output_config.format(oroutput_format) with document citations triggers an HTTP 400 error.
OpenAI: Hosted Vector Store Retrieval with File Search
OpenAI handles citations through the file_search tool within the Responses API. Rather than injecting raw text into every prompt, you upload files using the Files API with purpose set to assistants or user_data, create a vector store, and associate the files. When calling a model such as gpt-6-astra, you attach the tool and point to your vector store identifiers.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra",
input="What is deep research by OpenAI?",
tools=[{"type": "file_search", "vector_store_ids": ["<vector_store_id>"]}],
)
print(response)
- Automatic tool execution: The model inspects the prompt, emits a
file_search_call, queries the vector store, and returns amessageoutput item containing text with inlinefile_citationannotations. - Annotation structure: Citations provide a character
index, afile_id, and afilenamepointing to the retrieved document. - Retrieval controls: Developers can restrict context consumption and latency by adding
max_num_results(for example, setting it to 2) or applying metadatafilters(such as matching categories). - Optional payload details: Raw chunks retrieved during the tool step are omitted by default; setting
include: ["file_search_call.results"]includes them in the API response.
Google Gemini: Real-Time Grounding with Google Search
Google grounds responses in live web data through the google_search tool. Instead of referencing private vector stores or local documents, the model formulates search queries against public web content, retrieves results, and links statements to source URLs.
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Who won the euro 2024?",
tools=[{"type": "google_search"}]
)
print(interaction.output_text)
- Response annotations: Output steps contain
url_citationblocks featuringurl,title,start_index, andend_indexoffsets against the generated text string. - UI assets: The
google_search_resultstep returnssearch_suggestionsHTML markup intended for user interfaces as required by Google terms of service. - Pricing model: Gemini 3 and newer models bill per executed query rather than per prompt. Projects receive 5,000 free search requests per month across Gemini 3 and newer models, then pay $14 per 1,000 search requests. Empty search queries are excluded from billing.
- Tool interoperability: The
google_searchtool can run alongside custom function calling, code execution, URL context, and Google Maps grounding.
Provider Comparison: Capabilities and Output Formats
Selecting the right provider depends on whether your citation source is a closed private text, an indexed multi-file library, or the live public internet. Pricing and token implications also diverge significantly between providers. For underlying model input and output token rates, see /tools/llm-api-pricing/.
| Feature | Anthropic Claude | OpenAI Responses API | Google Gemini |
|---|---|---|---|
| Grounding Mechanism | Document content blocks in request payload | Hosted vector store tool (file_search) | Live web search tool (google_search) |
| Data Scope | User-supplied plain text and PDFs | Files uploaded to vector stores | Public web content |
| Citation Offsets | 0-indexed character offsets or 1-indexed PDF pages | 0-indexed character offsets in output text | start_index and end_index on output text |
| Extra Execution Costs | Standard input tokens (cited_text output is free) | Standard token usage across tool retrieval | $14 per 1,000 search requests (after 5,000 free/month) |
| Notable Constraints | Incompatible with structured output formats | Requires asynchronous vector store ingestion | Must display provided search suggestion widgets |
Implementation Checklist for Cited Responses
Before rolling citations or grounding into production workflows, review these operational requirements across your chosen stack:
- Check parameter compatibility: Verify that Claude calls enabling citations do not include
output_config.formatoroutput_formatparameters to avoid HTTP 400 errors. - Evaluate document boundaries: If using Claude with structured chunks or transcripts, use custom content documents rather than plain text to prevent sentence splitting from breaking logical boundaries.
- Configure prompt caching on documents: For repeated queries against the same reference material in Claude, attach
cache_control: {"type": "ephemeral"}to large document blocks to cut input token expenses. - Tune vector retrieval limits: Set
max_num_resultson OpenAI’sfile_searchtool to prevent unnecessary context consumption and control downstream latency. - Track search volumes: If running Gemini 3 models (such as
gemini-3.8-flashorgemini-3.1-pro-preview), count multi-query search executions to monitor your billing once you exceed the 5,000 monthly free request tier. For calculating end-to-end token costs, see /tools/llm-api-cost-calculator/.