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 type | Chunking | Citation type | Location fields |
|---|---|---|---|
| Plain text | Sentence | char_location | start_char_index / end_char_index (0-indexed, end exclusive) |
| Sentence | page_location | start_page_number / end_page_number (1-indexed, end exclusive) | |
| Custom content | None (blocks as-is) | content_block_location | start_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:
- All-or-none: "citations must be enabled on all or none of the documents within a request." You can't cite one document and leave another uncited in the same call.
- Only
sourcetext is citable: the optionaltitleandcontextfields are passed to the model but are never cited from. Usecontextto stash metadata (text or stringified JSON), sincetitleis length-limited.
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.cache_control on the document block — the citation blocks themselves can't be cached.DIAGRAM Enable → chunk → cited response
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_textis 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
output_config.format. → Returns a 400.
Citations and structured outputs are incompatible; pick one.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.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.