Claude's citations feature grounds answers in the documents you attach, returning the exact passages that support each claim. You enable it with citations: {"enabled": true} on a document content block. For teams budgeting a retrieval-augmented generation (RAG) workload — on the Claude API, Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, or Microsoft Foundry — the billing model has three parts worth understanding: a small cost you pay to turn it on, a meaningful discount you get on the citation text itself, and one hard incompatibility that fails fast with a 400 error.
The small cost: system-prompt overhead and chunking
Enabling citations slightly increases your input token count. Anthropic's documentation attributes this to two things: system prompt additions that instruct the model how to cite, and the document chunking the API performs so it has stable units to point at (plain-text documents are split into sentences; PDFs have their text extracted and sentence-chunked). This overhead is per-request and modest, but it is not zero — worth knowing if you are comparing token counts before and after turning citations on.
The discount: cited_text is never billed
Each citation Claude returns carries a cited_text field — the verbatim passage from your document. Two rules make this cheap:
cited_textdoes not count toward your output tokens, even though it appears in the response.- When you pass those citation blocks back in later turns of a conversation, the
cited_textdoes not count toward input tokens either.
Compare that to the do-it-yourself alternative, where you prompt the model to quote its sources in plain text: every quoted character is billed as output, and again as input on every subsequent turn. This is why Anthropic's docs claim cost savings over prompt-based quoting — along with guaranteed-valid pointers into the document and, in Anthropic's own evaluations, a higher likelihood of citing the most relevant passages.
| Item | Billed? |
|---|---|
| Citation system-prompt additions + chunking | Yes — small input-token increase |
| Your document blocks | Yes — normal input tokens (cacheable) |
cited_text in the response | No — excluded from output tokens |
cited_text passed back in later turns | No — excluded from input tokens |
Combining citations with prompt caching
Citations work with prompt caching, and the combination is the standard cost pattern for document Q&A: mark the document blocks with cache_control, then ask multiple questions against the cached copy. Cache reads are billed at 0.1x the base input price, so every question after the first reads the document at a tenth of the cost. The citation blocks themselves cannot carry cache_control — you cache the source documents, not the citations.
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")
resp = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": [
{"type": "document",
"source": {"type": "text", "media_type": "text/plain",
"data": long_policy_text},
"citations": {"enabled": True},
"cache_control": {"type": "ephemeral"}},
{"type": "text", "text": "What is the refund window?"},
]}],
)One caching caveat: toggling citations on or off between requests invalidates the system-and-messages portion of your prompt cache, because the rendered prompt changes. Pick a citation setting for a workload and keep it stable. Also note that citations must be enabled on all documents in a request or none of them — you cannot mix.
The hard stop: citations + structured outputs = 400
Citations are incompatible with structured outputs. If a request combines citation-enabled document or search_result blocks with output_config.format, the API returns a 400 error rather than silently dropping one feature. If you need both machine-readable output and attribution, the practical patterns are to run two passes, or to have the model emit JSON via a tool definition while keeping citations off — test what fits your pipeline.
Platform notes
Citations are available across the Claude API, Claude Platform on AWS, Bedrock, and Vertex AI; Microsoft's live Foundry documentation lists citations (including search_result blocks) as a supported capability. Citations are also eligible for Zero Data Retention and work with token counting and batch processing. For the mechanics of the feature itself, see the citations overview; for cache pricing details, see cache reads vs writes.