Skip to content

AI engines

Grounding, citations, annotations: how AI engines expose sources

Four shapes across six engines: OpenAI, Google, xAI and Microsoft return url_citation offsets, Claude up to 150 characters of cited_text, Perplexity ids.

Four outlined cubes hang from curved threads, with the last one circled in blue

SEO consultant, and more recently GEO, at MentionBox

Every engine that returns sources through an official API uses one of four shapes, and four of the six converge on the same object name. OpenAI's Responses API, the Gemini Interactions API, xAI's Responses API and Microsoft Foundry's web search tool all attach an annotation of type url_citation to the answer text, carrying a url, a title and start_index and end_index offsets. Anthropic puts a citations array on each text block instead, with up to 150 characters of cited_text per source. Perplexity hands back an integer id per retrieved page and inline [web:ID] markers in the text. And two Microsoft surfaces return nothing of the kind: the classic Grounding with Bing Search tool, whose documentation states that it "does NOT return the tool output to developers and end users", and Google AI Overviews and AI Mode, for which no API exists.

This page is for the developer who has to store answers from more than one engine in the same table, and for whoever needs to know which field holds the publisher's URL before writing the schema. It goes field by field through what each API returns, where the retrieved set and the cited set diverge, what each vendor requires you to display, and the three normalisation traps that cost a migration later.

The three things a source payload can carry

A source payload answers at most three questions, and no engine answers all three in full.

  • Which queries ran. The reformulated searches behind one prompt. Gemini returns them in google_search_call.queries, Perplexity in the queries array of its search_results item, OpenAI in web_search_call.action.queries, and Claude one at a time in the input.query of each server_tool_use block. xAI and Microsoft Foundry return none. Our explainer on query fan-out in AI search covers how far that expansion goes.
  • Which pages were retrieved. The candidate set, before the model picked from it. OpenAI exposes it only if you ask, Anthropic and Perplexity expose it by default, and the other three do not expose it at all.
  • Which sentence rests on which page. The anchor. Four engines give character offsets, Anthropic gives a quoted passage, Perplexity gives an id, and Microsoft's classic tool gives nothing.

Those three questions are the whole difference between a link list and a dataset you can audit.

What each engine returns, field by field

OpenAI, Responses API

A searched call produces two kinds of output item. A web_search_call item records what the tool did, with an id, a status and an action whose type is search, open_page or find_in_page; the search action carries the queries. A message item carries the text, with url_citation annotations holding the type, the url, the title, the start_index and the end_index.

The retrieved set is opt-in. Adding web_search_call.action.sources to the request's include parameter returns it, and the guide for the tool draws the line explicitly: "unlike inline citations, which show only the most relevant references, sources returns the complete list of URLs the model consulted when forming its response", adding that "the number of sources is often greater than the number of citations". The same page sets a display rule, which is the part most integrations miss: "when your interface displays web results or information from them, you must show inline citations as prominent, clickable links". The search is billed at $10 per 1,000 calls plus the content tokens.

Google, Gemini API

Two shapes are in circulation and they name nothing the same way. The current Interactions API returns a steps array: a google_search_call with the queries the model ran, a google_search_result holding a search_suggestions field that Google's grounding guide describes as "an HTML snippet for rendering search suggestions in your UI", and a model_output whose text blocks carry annotations of type url_citation with a url, a title given as the domain name, a start_index and an end_index.

The legacy generateContent shape puts everything in a groundingMetadata object instead, with webSearchQueries, a searchEntryPoint.renderedContent for the same HTML, a groundingChunks array of web.uri and web.title pairs, and a groundingSupports array that maps a text segment with startIndex, endIndex and text onto groundingChunkIndices. That last array is the finest-grained anchor any engine publishes, because it links one passage to several chunks at once.

Two gaps belong with it. The chunk uri is a Google redirect on vertexaisearch.cloud.google.com rather than the publisher's address, with the title reduced to the bare domain, and a feature request for actual source URLs has sat on Google's developer forum since 2026 without a published answer. And the retrieved set is not exposed: the search result step carries the Search Suggestions snippet, not a result list. Grounding is billed per query the model decides to run, at $14 per 1,000 search requests on Gemini 3 and newer after 5,000 free a month, under a default ceiling of 1,500 requests a day. Our decryption of grounding with Google Search covers what the terms allow you to keep.

Anthropic, Claude API

The Claude API is the only one of the six that returns the retrieved page, the cited passage and the search query in the same content array, in reading order. Anthropic's web search guide publishes the whole response: a server_tool_use block with the query, a web_search_tool_result block whose content is a list of web_search_result entries with a url, a title, a page_age described as "when the site was last updated" and an encrypted_content blob, then a text block with a citations array.

Each citation is a web_search_result_location with a url, a title, an encrypted_index and cited_text, which the guide caps at "up to 150 characters of the cited content". Two details are specific to this API. The guide states that "the web search citation fields cited_text, title, and url do not count toward input or output token usage", so the citation layer is free once the search is paid. And encrypted_content has to be sent back unmodified on later turns, or the request fails with a 400, which makes a multi-turn log heavier than a single-answer log. Searches cost $10 per 1,000, and tool version web_search_20260318 adds a response_inclusion parameter whose "excluded" value drops the raw result blocks from the response for agent workflows that only need the answer.

Perplexity, Agent API

Perplexity is the outlier on the anchor. The output array contains an item of type search_results with a queries array and a results array, each entry holding an id, url, title, snippet, source, date and last_updated, and the answer text points back with inline [web:ID] markers rather than character offsets. Its documentation advises treating the id and url fields as the source of truth for citations rather than parsing the numbers out of the prose.

Two fields here exist nowhere else: date and last_updated give the publication date and the freshness of each cited page without a second fetch. The third Perplexity endpoint, the Orchestrator chat completions route, switches to annotations with url_citation objects carrying url, title, start_index and end_index, so one vendor ships both shapes depending on which address you call. The web_search tool is billed at $2.50 per 1,000 invocations, or $1.00 with Fast Search, fetch_url at $0.50 per 1,000, and the standalone Search API at $5.00 per 1,000 requests, or $1.00 with Fast Search. Our decryption of the Sonar migration and the Agent API covers the rest of the move.

xAI, Grok

Grok returns a visit log and an optional anchor. response.citations comes back by default as a flat list of every URL the agent reached, including pages it opened and discarded, so it is wider than a cited set. Inline citations are the anchor, as url_citation annotations with a url, a title, a start_index and an end_index, on by default on the Responses API and off by default in the xAI Python SDK, where include=["inline_citations"] turns them on. The citations page warns that "enabling inline citations does not guarantee that the model will cite sources on every answer" and that "the model decides when and where to include citations based on the context and nature of the query". The web_search tool costs $5 per 1,000 calls; our piece on Grok's search tools covers the rest of the billing.

Microsoft, Foundry Agent Service

Microsoft runs two generations with opposite behaviour, and the older one is the reason many developers assume Copilot exposes nothing. The classic Grounding with Bing Search tool states that "developers and end users don't have access to raw content returned from Grounding with Bing Search" and that the tool "does NOT return the tool output to developers and end users". What does come back is a pair of references, the website URLs through the annotations parameter and the Bing search query URL through the run step details, and Microsoft requires both: they "must be retained and displayed in the exact form provided by Microsoft". It is billed at $14 per 1,000 transactions, capped at 150 per second and 1 million a day.

The current web search tool looks like the rest of the field: an output_text content block with annotations of type url_citation, and the example in the documentation shows a url, a start_index and an end_index. One line on that page deserves a note in your schema, because it changes what you are measuring without changing a single parameter: "when you add web search directly to a prompt agent or a Responses API request, it uses Web IQ", while "when you add web search to a toolbox, it still uses Grounding with Bing Search, not Web IQ". The same tool name therefore reads two different indexes.

Side by side

EngineWhere the cited set livesAnchor to the answerRetrieved setQueriesPrice of the search
OpenAI, Responses APIurl_citation annotations on the messagestart_index, end_indexopt-in, via include: ["web_search_call.action.sources"]web_search_call.action.queries$10 per 1,000 calls
Google, Gemini Interactionsurl_citation annotations on model_outputstart_index, end_indexnot returnedgoogle_search_call.queries$14 per 1,000 search requests, 5,000 free a month
Google, generateContentgroundingChunks[].web.urigroundingSupports[] segment to chunk indicessame array as the cited setwebSearchQueriessame
Anthropic, Claude APIcitations[] on each text blockcited_text, up to 150 charactersweb_search_tool_result blocksone query per server_tool_use$10 per 1,000 searches
Perplexity, Agent APIsearch_results.results[][web:ID] markers, matched on idsame array as the cited setsearch_results.queries$2.50 per 1,000, $1.00 with Fast Search
xAI, Responses APIresponse.citationsurl_citation annotations, when the model adds themcitations doubles as a visit lognot returned$5 per 1,000 calls
Microsoft Foundry, web searchurl_citation annotations on output_textstart_index, end_indexnot returnednot returned$14 per 1,000 Bing grounding transactions

Field names from each vendor's own documentation and rates from each vendor's pricing page, read on November 20, 2026.

Normalising six shapes into one table

Six payloads collapse into seven columns, and the mapping is mechanical once you accept that two of them are often empty.

ColumnRead it from
answer_textoutput_text on OpenAI, Perplexity, xAI and Foundry; the concatenated text blocks on Claude; model_output text on Gemini
searchedpresence of web_search_call, google_search_call, server_tool_use, a search_results item, or a non-empty citations
queries[]action.queries, google_search_call.queries, search_results.queries, or one per server_tool_use
retrieved[]action.sources, web_search_tool_result.content[], search_results.results[], groundingChunks[]
cited[]the annotation array, the citations array, or the ids referenced by [web:ID] markers
anchorstart_index and end_index, or cited_text, or the result id, or null
publisher_urlthe url field, except on Gemini's generateContent, where the redirect has to be resolved

On OpenAI the whole extraction fits in one call, and the two arrays you want are siblings rather than nested:

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": "best AI visibility API for an agency",
    "tools": [{"type": "web_search"}],
    "tool_choice": "required",
    "include": ["web_search_call.action.sources"]
  }' | jq '{
    queries: [.output[] | select(.type == "web_search_call") | .action.queries?] | flatten,
    retrieved: [.output[] | select(.type == "web_search_call") | .action.sources?] | flatten,
    cited: [.output[] | select(.type == "message") | .content[].annotations[]?
            | select(.type == "url_citation") | .url]
  }'

Three traps sit in that mapping, and each one is cheaper to handle on the way in than in a migration.

  1. Response-scoped ids. Perplexity's result id is an integer index local to one response, reused on the next call. Key your rows on the URL and keep the id only to resolve the markers inside that same answer.
  2. Redirects stored as URLs. A vertexaisearch.cloud.google.com address and a publisher address are not the same key. Store the domain from web.title and the redirect separately, and resolve only when you need the page, inside what the terms allow.
  3. Empty rows that look like failures. An answer with no search step is a valid observation, not a dropped record. Without a searched boolean, a month of logs mixes two populations and no later analysis separates them.

What each vendor requires you to display

The citation fields come with obligations, and they differ enough that one interface cannot satisfy all six by accident.

  • OpenAI. Inline citations shown as prominent, clickable links whenever the interface displays web results or information drawn from them.
  • Google. The Search Suggestions HTML displayed with the grounded results, capped at five, unmodified and with nothing interspersed; the Gemini API terms also limit storage of grounded text to two years for three named purposes and forbid caching, analysing or collecting the links.
  • Anthropic. Citations to the original source when API outputs are displayed directly to end users, with its own note that modified or recombined outputs are a question for your legal team.
  • Microsoft. Both the website URLs and the Bing search query URL, retained and displayed in the exact form Microsoft provides, per the Grounding with Bing use and display requirements.
  • Perplexity and xAI. No display rule published on the citation pages themselves, which is not the same as permission to store at volume; retention sits in each vendor's privacy terms.

In our view that list, rather than the field names, is what decides whether a given API can sit behind the product you are building. A reporting tool that counts domains and shows a client a table of who gets cited is a different activity from an application that answers one reader's question with links, and the Gemini terms separate the two in writing.

What no source payload contains

All six return one answer with its sources. None of them returns a position, a share of voice, a count across repeated runs, or the competitor names that appeared beside yours, and none of them returns what a person sees in the consumer product: Google publishes no API for AI Overviews or AI Mode, and the Microsoft note above says the classic Bing grounding tool withholds its raw output by design. The formulas for the computed layer are in our guide on GEO metrics, and the counting rules per page in our guide on tracking the AI citations of your pages.

As a concrete example of what that layer looks like when a vendor ships it rather than leaving it to you, API for GEO returns a sources[] array per prompt with the url, the domain, a category and a mentionsBrand flag, alongside brand mentions, position, share of voice, sentiment and the fan-out questions, at $13 per 1,000 answers down to $7 at its largest tier, with reads over stored runs not billed, checked on October 23, 2026. MentionBox, which publishes this site, has a commercial link with API for GEO.

The field names will keep moving. Google already runs two shapes at once, Perplexity ships two, Microsoft swapped the behaviour of its tool between generations, and Anthropic added a parameter in its latest tool version that removes result blocks from the response entirely. What has held steady since the first of these tools shipped is the three questions above: which queries ran, which pages came back, and which sentence rests on which page. A table built on those three survives a vendor renaming its fields.

Frequently asked questions

How do I get the list of sources an AI engine used through its API?

Read the citation object the engine attaches to the answer, whose name differs by vendor. On OpenAI's Responses API and on xAI, Google and Microsoft Foundry, it is an annotation of type `url_citation` on the text content, with a `url`, a `title` and `start_index` and `end_index` offsets. On the Claude API it is a `citations` array on each text block, holding `url`, `title`, `encrypted_index` and up to 150 characters of `cited_text`. On Perplexity's Agent API it is an `output` item of type `search_results`, whose `results` entries carry an `id`, `url`, `title`, `snippet`, `source`, `date` and `last_updated`.

What is the difference between grounding, citations and annotations?

Grounding is the step, citations are the result, annotations are the transport. Google calls the whole feature grounding with Google Search and bills it at $14 per 1,000 search requests on Gemini 3 and newer after 5,000 free a month; the citations are the pages it attributes the answer to; and the annotations are the objects that tie a character range of the text to one of those pages. Anthropic and Perplexity use the word citation for both the object and the result, and Anthropic's documentation states that citations "are always enabled for web search".

Which engines return the real publisher URL of a cited page?

Five of the six, with Google the exception in the shape most integrations read. Claude returns the page `url` directly, Perplexity returns a publisher `url` per result, OpenAI and xAI return a `url` per annotation, and Microsoft Foundry's web search tool returns a `url` on each `url_citation`. In Gemini's legacy generateContent shape each grounding chunk carries a `web.uri` on `vertexaisearch.cloud.google.com` with a `web.title` cut down to the domain, so the publisher address is reached by following the redirect. A feature request asking for actual source URLs has been open on Google's developer forum since 2026 without a published answer.

Does every searched answer come back with citations?

No, and two vendors say so in writing. xAI's citations page states that "enabling inline citations does not guarantee that the model will cite sources on every answer" and that "the model decides when and where to include citations based on the context and nature of the query". OpenAI's guide notes that "the number of sources is often greater than the number of citations", so a page can be retrieved, read and never cited. Store a boolean for whether a search ran at all, since an answer with no search step came out of the model's weights rather than the web.

Am I allowed to store and display the citations an API returns?

Each vendor sets its own rule, and three of them are explicit. OpenAI's guide states that when your interface displays web results "you must show inline citations as prominent, clickable links". Anthropic notes that "when displaying API outputs directly to end users, citations must be included to the original source". Microsoft requires both the website URLs and the Bing search query URLs to be shown, "retained and displayed in the exact form provided by Microsoft". The Gemini API terms are the most restrictive of the set: grounded text may be kept for up to two years for three named purposes only, with caching, analysis and link collection forbidden.

How much does a searched answer with its citations cost on each API?

The search is billed separately from the tokens. OpenAI charges $10 per 1,000 web search calls, Anthropic $10 per 1,000 searches, Google $14 per 1,000 search requests on Gemini 3 and newer after 5,000 free a month, xAI $5 per 1,000 web search calls, Perplexity $2.50 per 1,000 `web_search` invocations or $1.00 with Fast Search, and Microsoft $14 per 1,000 Grounding with Bing Search transactions. Rates read on each vendor's pricing page on November 20, 2026. The pages the search feeds the model are billed on top as input tokens at the model's own rate.