Citations

Claude is capable of providing detailed citations when answering questions about documents, helping you track and verify information sources in responses.

All active models support citations, with the exception of Haiku 3.

Here's an example of how to use citations with the Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 Document",
                    "context": "This is a trustworthy document.",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "What color is the grass and sky?"},
            ],
        }
    ],
)
print(response)

How citations work

Integrate citations with Claude in these steps:

Citable vs non-citable content

• Text found within a document's source content can be cited from.
• title and context are optional fields that will be passed to the model but not used towards cited content.
• title is limited in length so you may find the context field to be useful in storing any document metadata as text or stringified json.

Citation indices

• Document indices are 0-indexed from the list of all document content blocks in the request (spanning across all messages).
• Character indices are 0-indexed with exclusive end indices.
• Page numbers are 1-indexed with exclusive end page numbers.
• Content block indices are 0-indexed with exclusive end indices from the content list provided in the custom content document.

Token costs

• Enabling citations incurs a slight increase in input tokens due to system prompt additions and document chunking.
• However, the citations feature is very efficient with output tokens. Under the hood, the model is outputting citations in a standardized format that are then parsed into cited text and document location indices. The cited_text field is provided for convenience and does not count towards output tokens.
• When passed back in subsequent conversation turns, cited_text is also not counted towards input tokens.

Feature compatibility

Citations works in conjunction with other API features including prompt caching, token counting and batch processing.

Using Prompt Caching with Citations

Citations and prompt caching can be used together effectively.

The 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.

In this example:

• The document content is cached using cache_control on the document block
• Citations are enabled on the document
• Claude can generate responses with citations while benefiting from cached document content
• Subsequent requests using the same document will benefit from the cached content

Document Types

Choosing a document type

Three document types are supported for citations. Documents can be provided directly in the message (base64, text, or URL) or uploaded via the Files API and referenced by file_id:

Plain text documents

Plain text documents are automatically chunked into sentences. You can provide them inline or by reference with their file_id:

PDF documents

PDF documents can be provided as base64-encoded data or by file_id. PDF text is extracted and chunked into sentences. As image citations are not yet supported, PDFs that are scans of documents and do not contain extractable text will not be citable.

Custom content documents

Custom content documents give you control over citation granularity. No additional chunking is done and chunks are provided to the model according to the content blocks provided.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"},
        ],
    },
    "title": "Document Title",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "citations": {"enabled": True},
}

Response Structure

When citations are enabled, responses include multiple text blocks with citations:

{
    "content": [
        {"type": "text", "text": "According to the document, "},
        {
            "type": "text",
            "text": "the grass is green",
            "citations": [
                {
                    "type": "char_location",
                    "cited_text": "The grass is green.",
                    "document_index": 0,
                    "document_title": "Example Document",
                    "start_char_index": 0,
                    "end_char_index": 20,
                }
            ],
        },
        {"type": "text", "text": " and "},
        {
            "type": "text",
            "text": "the sky is blue",
            "citations": [
                {
                    "type": "char_location",
                    "cited_text": "The sky is blue.",
                    "document_index": 0,
                    "document_title": "Example Document",
                    "start_char_index": 20,
                    "end_char_index": 36,
                }
            ],
        },
        {
            "type": "text",
            "text": ". Information from page 5 states that ",
        },
        {
            "type": "text",
            "text": "water is essential",
            "citations": [
                {
                    "type": "page_location",
                    "cited_text": "Water is essential for life.",
                    "document_index": 1,
                    "document_title": "PDF Document",
                    "start_page_number": 5,
                    "end_page_number": 6,
                }
            ],
        },
        {
            "type": "text",
            "text": ". The custom document mentions ",
        },
        {
            "type": "text",
            "text": "important findings",
            "citations": [
                {
                    "type": "content_block_location",
                    "cited_text": "These are important findings.",
                    "document_index": 2,
                    "document_title": "Custom Content Document",
                    "start_block_index": 0,
                    "end_block_index": 1,
                }
            ],
        },
    ]
}

Streaming Support

For streaming responses, a citations_delta type is included that contains a single citation to be added to the citations list on the current text content block.