citations changedbuild-with-claude/citations
Nearest release: v2.1.315, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+62added
Lines−3removed
From line
398
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits20to this page, all time
## Feature compatibility ### Get structured data with citations ### Using prompt caching with citations ### Feature compatibility #### Using prompt caching with citations
The whole hunk
from line 398, old and new numbered
/
from line 398
398398* However, the citations feature is very efficient with output tokens. Internally, the model outputs citations in a standardized format, and those citations are then parsed into cited text and document location indices. The `cited_text` field is provided for convenience and does not count toward output tokens.
399399* When passed back in subsequent conversation turns, `cited_text` is also not counted toward input tokens.
400400
401### Feature compatibility
401## Feature compatibility
402402
403403Citations work in conjunction with other API features including [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting), and [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing).
404404
from line 410
410410 This is because citations require interleaving citation blocks with text output, which is incompatible with the strict JSON schema constraints of structured outputs.
411411</Warning>
412412
413#### Using prompt caching with citations
413### Get structured data with citations
414414
415To get a citation for each extracted value, prompt Claude to answer with one line per field. Then parse the lines into structured data in your code.
416
417Avoid user or system prompts that ask for only JSON, such as “Return only a JSON object, no other text.” A request with such a prompt succeeds, but the response might contain few or no citations.
418
419The following prompt asks for two fields from the plain text document in the example at the top of this page. Send it in place of that example’s question:
420
421```text wrap
422Extract these fields from the document: grass_color, sky_color.
423Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.
424```
425
426In the following response, each value has its own citations:
427
428```json
429{
430 "content": [
431 { "type": "text", "text": "grass_color: " },
432 {
433 "type": "text",
434 "text": "green",
435 "citations": [
436 {
437 "type": "char_location",
438 "cited_text": "The grass is green. ",
439 "document_index": 0,
440 "document_title": "My Document",
441 "start_char_index": 0,
442 "end_char_index": 20
443 }
444 ]
445 },
446 { "type": "text", "text": "\nsky_color: " },
447 {
448 "type": "text",
449 "text": "blue",
450 "citations": [
451 {
452 "type": "char_location",
453 "cited_text": "The sky is blue.",
454 "document_index": 0,
455 "document_title": "My Document",
456 "start_char_index": 20,
457 "end_char_index": 36
458 }
459 ]
460 }
461 ]
462}
463```
464
465To parse the response, follow these steps:
466
4671. Read the `text` blocks in order, and add each block’s text to the current line. Start a new line at each newline character.
4682. Attach each block’s `citations` to every line that contains part of its text. A cited block can hold only a value, as in this example, or a whole line.
4693. Skip lines that have no colon. Split each remaining line at its first colon into a field name and a value, and trim spaces from both. Skip lines whose name isn’t one of your fields, such as a closing note.
4704. Check that each field has a value and at least one citation. The API doesn’t guarantee either.
471
472### Using prompt caching with citations
473
415474Citations and prompt caching can be used together effectively.
416475
417476The citation blocks generated in responses cannot be cached directly, but the source documents they reference can be cached. To optimize performance, apply `cache_control` to your top-level document content blocks.
from line 2243
21842243 "citations": [
21852244 {
21862245 "type": "char_location",
2187 "cited_text": "The grass is green.",
2246 "cited_text": "The grass is green. ",
21882247 "document_index": 0,
21892248 "document_title": "Example Document",
21902249 "start_char_index": 0,
No line in this hunk matches that.