# Anthropic — Citations and search results

Status: DOCUMENTED · LIVE_VERIFIED (claude-haiku-4-5-20251001: char_location, page_location, content_block_location, search_result_location, citations_delta, Files API document). GA, no beta header (search-results-2025-06-09 retired 2025-08-08). Sources: Citations · Search results · PDF support · Messages API Last verified: 2026-09-18

# Enabling

Set "citations": {"enabled": true} on every document / search_result block (all-or-nothing: mixing → 400 Citations must be either enabled or disabled on all document blocks. A mixture of enabling and disabling is not supported at this time.). Supported on all active models (Haiku 3 excluded for search results). Only text is citable (no image citations; scanned PDFs without text are not citable). title and context are visible to the model but not citable.

# Document types → citation types

Input block	Source	Chunking	Citation `type`	Indices	Live
`document`	`{"type": "text", "media_type": "text/plain", "data"}`	sentences	`char_location`	`start_char_index` (0-based), `end_char_index` (exclusive), `document_index`, `document_title`	`"Grass is green."` → 17–32
`document`	`{"type": "base64", "media_type": "application/pdf", "data"}` / `url` / `file`	text extracted per page, sentences	`page_location`	`start_page_number` (1-based), `end_page_number` (exclusive)	1-page PDF → 1–2 (2,130 input tokens for a 1-page PDF with citations)
`document`	`{"type": "content", "content": [text blocks]}` (custom content)	none — your blocks	`content_block_location`	`start_block_index`, `end_block_index` (exclusive)	block 1 → 1–2
`document`	`{"type": "file", "file_id"}` (text/plain or PDF from Files API)	as above	`char_location` / `page_location` + `file_id` field (`document_title` null unless `title` given)	text: 17–33; PDF: pages 1–2	`file_id` is absent from the docs/API reference tables but present in the SDK response models (Python `model_dump()` shows `file_id: None` on other citations) → `LIVE_DISCOVERED`
`search_result`	`source` (string), `title`, `content: [text…]`	none — your blocks	`search_result_location`	`search_result_index`, `start_block_index`, `end_block_index`, `source`, `title`	index 0, blocks 1–2
web search tool result	server tool	—	`web_search_result_location`	`url`, `title`, `encrypted_index`	not exercised

document_index / search_result_index count blocks of that kind across all messages (including tool results) in request order.

# Response shape

json

{"type": "text", "text": "Grass is green.",
 "citations": [{"type": "char_location", "cited_text": "Grass is green.", "document_index": 0,
                "document_title": "Colors", "start_char_index": 17, "end_char_index": 32}]}

Responses may contain several text blocks, each with its own citations list. Streaming: content_block_delta with delta.type: "citations_delta" carrying one citation to append to the current text block (live captured).

# Search results (`search_result` blocks)

Fields: type: "search_result", source (any stable string, e.g. kb://article-1234), title, content (array of non-empty text blocks), optional citations, cache_control.
Provide them as user content or return them from a custom tool (tool_result.content must then be all search_result blocks). Assistant messages may not contain them. With the web search tool enabled, all search_result blocks must have citations enabled.
Granularity = one text block: split content for finer citations. cited_text = the cited blocks joined.

# Costs and compatibility

Slight input increase (system prompt + chunking). cited_text is not billed as output, and not billed as input when replayed.
Works with prompt caching (cache the document blocks, not the citations), token counting, Batches, PDFs from URL/base64/Files.
Incompatible with structured outputs: citations + output_config.format → 400 Citations cannot be enabled when output format is set… (live).
Toggling citations changes the system prompt → invalidates system + messages caches.

# Live log (Haiku 4.5, 2026-09-18)

Call	Input tokens	Result
text document, "What color is grass?"	591	`char_location` 17–32
search_result (2 blocks)	609	`search_result_location` index 0, blocks 1–2
custom content document	582	`content_block_location` blocks 1–2
generated 1-page PDF (base64)	2,130	`page_location` pages 1–2
streaming text document	591	`citations_delta` event
Files API text/plain `file_id`	613	`char_location` + `file_id`, `document_title: null`
mixed enabled/disabled	—	400

Examples: examples/anthropic/citations/ · tests: tests/anthropic/test_vision_documents.py.