# 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](https://platform.claude.com/docs/en/build-with-claude/citations) · [Search results](https://platform.claude.com/docs/en/build-with-claude/search-results) · [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support) · [Messages API](https://platform.claude.com/docs/en/api/messages/create)
**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`.