D5 · Context & Reliability › Cluster 4 · Long Context & Retrieval

4.4 · Citations & Grounding at Scale

Answers tied to sources

CONCEPT The Citations feature ties claims to exact source spans

Rather than prompting Claude to cite, the Citations feature makes the API return claims already bound to their sources. You pass documents as document content blocks with "citations": {"enabled": true}; the response splits into multiple text blocks, and each block that makes a claim carries a citations array. Every citation includes the exact cited_text, a document_index, a document_title, and a location whose shape depends on the document type.

Document typeChunkingCitation typeLocation fields
Plain textSentencechar_locationstart_char_index / end_char_index (0-indexed, end exclusive)
PDFSentencepage_locationstart_page_number / end_page_number (1-indexed, end exclusive)
Custom contentNone (blocks as-is)content_block_locationstart_block_index / end_block_index (0-indexed, end exclusive)
🔑 cited_text does not count toward output tokens — the model emits a compact citation and the API fills in the quoted text. When passed back in later turns, it's also not counted toward input tokens. All active models support citations except Claude Haiku 3.

CONCEPT The all-documents-or-none rule & what's citable

Two rules the exam loves:

Custom content documents give you citation granularity control: your content blocks are used as-is with no further chunking — ideal for bullet lists, transcripts, or citing whole RAG chunks. Plain text and PDF are auto-chunked into sentences.
Incompatible with structured outputs. If you enable citations on any document (or search_result) block and also pass output_config.format (or the deprecated output_format), the API returns a 400. Citations interleave citation blocks with text, which the strict JSON-schema constraint of structured outputs cannot accommodate.
Citations do work with prompt caching, token counting, and batch processing. Cache the source documents with cache_control on the document block — the citation blocks themselves can't be cached.

DIAGRAM Enable → chunk → cited response

flowchart TD A["document blocks
citations.enabled = true
(ALL or NONE)"] --> C{"Document type?"} C -->|"plain text / PDF"| S["Auto-chunk into sentences"] C -->|"custom content"| B["Blocks used as-is
(no chunking)"] S --> R["Response: text blocks;
claim blocks carry a
citations[ ] array"] B --> R R --> X["🔴 + output_config.format
→ 400 error"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class S ok; class B ok; class R ok; class X bad;

CODE Enabling citations and reading the spans

Enable on each document, cache the source, then walk the response for cited text and locations.

resp = client.messages.create(
    model="claude-opus-4-8", 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 Doc", "context": "trustworthy source",  # not cited from
         "citations": {"enabled": True},                # ALL-or-none per request
         "cache_control": {"type": "ephemeral"}},          # cache the source doc
        {"type": "text", "text": "What color is the grass and sky?"},
    ]}],
    # NOTE: do NOT add output_config.format here → citations + structured output = 400
)

for block in resp.content:
    if block.type == "text" and getattr(block, "citations", None):
        for c in block.citations:
            # c.type: char_location | page_location | content_block_location
            print(c.cited_text, "←", c.document_title, c.document_index)

TRADE-OFFS Citations feature vs. prompting for quotes

✅ Citations feature

  • Spans are guaranteed valid pointers into your docs
  • cited_text is free on output tokens
  • More likely to cite the most relevant quotes
  • Works with caching, token counting, batches

⚠️ Just prompting "please cite"

  • Quotes count as output tokens
  • No guarantee the quote actually exists in the source
  • No structured index back to char/page/block
  • But: composes with output_config.format (citations don't)

EXAM TRAPS

Trap: "Enable citations on the important documents only." → No — all or none per request. Mixed enablement isn't allowed.
Trap: Combining citations with output_config.format. → Returns a 400. Citations and structured outputs are incompatible; pick one.
Trap: Expecting cited_text to inflate output-token cost, or citing from title/context. → cited_text is not billed as output; and only the document source is citable — title/context are never cited from.
Trap: Assuming one location shape for everything. → Plain text → char_location (0-indexed chars), PDF → page_location (1-indexed pages), custom content → content_block_location (0-indexed blocks). All end indices are exclusive.

PRACTICE

Q1 · A request cites one of three documents and leaves two uncited. Valid?

No. Citations must be enabled on all or none of the documents within a request. Enable it on all three, or none.

Q2 · Why does adding output_config.format to a citations request fail?

Citations and structured outputs are incompatible — the API returns a 400. Citations interleave citation blocks with the text output, which can't coexist with the strict JSON-schema constraint of output_config.format (or the deprecated output_format).

Q3 · What location fields come back for a PDF vs. plain text citation?

PDF → page_location with start_page_number/end_page_number (1-indexed, exclusive end). Plain text → char_location with start_char_index/end_char_index (0-indexed, exclusive end). Custom content → content_block_location with block indices. Every citation also carries cited_text, document_index, and document_title.