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.

By ailog · Published Oct 24, 2026 · 5 min read · How we work
In short
  • 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_text does 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 (or output_format) with document citations triggers an HTTP 400 error.

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 a message output item containing text with inline file_citation annotations.
  • Annotation structure: Citations provide a character index, a file_id, and a filename pointing 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 metadata filters (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 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_citation blocks featuring url, title, start_index, and end_index offsets against the generated text string.
  • UI assets: The google_search_result step returns search_suggestions HTML 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_search tool 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.format or output_format parameters 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_results on OpenAI’s file_search tool to prevent unnecessary context consumption and control downstream latency.
  • Track search volumes: If running Gemini 3 models (such as gemini-3.8-flash or gemini-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/.
Sources
  1. Citations
  2. File search
  3. https://ai.google.dev/gemini-api/docs/google-search

Related