Ground answers in source documents the supported way.
1. Pass documents as document blocks. Use type document with a source (text with media_type text/plain, or a PDF as base64 or url or file_id), an optional title and context, and citations set to enabled. Context is passed to the model but is not citable; title helps the model label sources.
2. Enable citations on all documents or none. The docs are explicit: within one request, citations must be enabled on all documents or on none of them. Mixing enabled and disabled documents is not supported.
3. Check the model exception. All active models support citations. If you are on an old pinned model and citations silently do nothing, confirm the model is not an excluded legacy one, then upgrade the pin.
4. Tell the model to cite when you constrain the format. The model is less likely to cite when you ask for a structured response (for example wrapped in result tags) unless you explicitly say to use citations inside that format. Add one line: always use citations in your answer, even inside the required format.
5. Read the citations, not just the text. Responses interleave plain text blocks with text blocks carrying a citations array. Each citation gives cited_text plus a location: char_location for plain text (start and end char indexes), page_location for PDFs (start and end page numbers), or content_block_location for custom content (start and end block indexes), plus document_index and document_title.
6. Verify programmatically. For each citation, check that cited_text actually appears in the referenced document at the given location. A citation whose text does not exist in the source means the claim is unsupported: surface that to the user instead of the answer.
7. Handle streaming deltas. In streaming mode, citations arrive as citations_delta events inside content_block_delta, one citation at a time appended to the current block. Accumulate them per block and only render citations once the block is complete.