Leveraging Citations in Results

Traceable Answers with Citations

When a user asks your application a factual question, they want to verify the information. The Grok API citations meet this need exactly: every fact retrieved via web search comes with its source. This lets you build interfaces where every claim is clickable and verifiable.

The API offers two complementary citation mechanisms: global citations and inline citations. Understanding how they work lets you create professional, transparent user experiences.

Global Citations: The Complete Source List

Global citations are returned by default in the citations attribute of the response. They contain a list of all URLs consulted by the model, even those not directly referenced in the response text.

response = client.responses.create(
    model="grok-4.5",
    input="What are the latest AI regulations in Europe?",
    tools=[{"type": "web_search"}]
)

# Access global citations
for citation in response.citations:
    print(f"Source: {citation.url}")

No additional configuration is required. This is the native behavior of the API.

Inline Citations: References in the Text

Inline citations insert Markdown links directly into the response text, using the format [[N]](url) where N is a sequential number starting at 1. If the same source is cited multiple times, the original number is reused.

Default behavior depends on the SDK used:

• Direct Responses API: inline citations enabled by default
• xAI SDK: inline citations disabled by default (opt-in)

Enable Inline Citations with the xAI SDK

response = client.responses.create(
    model="grok-4.5",
    input="Current status of the European AI Act",
    tools=[{"type": "web_search"}],
    include=["inline_citations"]
)

Disable Inline Citations on the Responses API

response = client.responses.create(
    model="grok-4.5",
    input="Current status of the European AI Act",
    tools=[{"type": "web_search"}],
    include=["no_inline_citations"]
)

The Structured Annotation Schema

Each inline citation generates an annotation object with precise metadata. This structure enables advanced programmatic processing:

{
  "type": "url_citation",
  "url": "https://eur-lex.europa.eu/eli/reg/2024/1689",
  "start_index": 145,
  "end_index": 178,
  "title": "1"
}

The start_index and end_index fields follow Python slice convention. You can use them to extract the exact cited text or create custom HTML rendering:

text = response.output_text

for annotation in response.annotations:
    cited_text = text[annotation.start_index:annotation.end_index]
    print(f"Cited text: {cited_text}")
    print(f"Source: {annotation.url}")

Streaming Behavior

When using streaming, inline citations appear progressively in the text chunks. However, complete annotations are only available in the final response. Plan for two-stage processing if your interface displays sources in real time.

Building an Interface with Sources

Here’s an example of transforming citations into structured HTML:

def format_response_with_sources(response):
    text = response.output_text
    sources = []

    # Collect unique sources
    seen_urls = set()
    for citation in response.citations:
        if citation.url not in seen_urls:
            sources.append(citation.url)
            seen_urls.add(citation.url)

    # Build the render
    html = f"<div class='response'>{text}</div>"
    html += "<div class='sources'><h4>Sources</h4><ul>"
    for i, url in enumerate(sources, 1):
        html += f"<li><a href='{url}'>[{i}] {url}</a></li>"
    html += "</ul></div>"

    return html

Collection Citations

If you use the collections_search tool alongside web_search, citations from your uploaded documents use a specific URI format: collections://collection_id/files/file_id. Distinguish these from standard web citations to adapt the front-end rendering.

Hands-On Practice

Create an application that displays Grok search results with a footnote system. Each fact should link back to its original source. Test with current events questions and manually verify that the links are valid and relevant.

Key Takeaways

• Global citations (URL list) are returned by default, without configuration
• Inline citations (links in text) are enabled via the include parameter
• Default inline citation behavior varies by SDK
• Each annotation contains the URL, position indices, and citation number
• In streaming, complete annotations are only available in the final response
• Collection citations use a distinct URI format (collections://)