Trust & citations

Every answer ships with the evidence behind it. This page explains how to make that evidence visible and honest in your UI.

Audience: developers building user-facing answer displays. What you will accomplish: render citations, compute a confidence indicator, and handle refusals correctly.

The citation object

Each entry in sources[] is a structured object:

Field	Meaning
`label`	Human-readable source name, e.g. `return_policy.pdf`.
`doc_id`	Stable document id used by ingest/delete.
`score`	Relevance of this chunk to the question (0–1).
`page`	Page number (when available) for verification.
`snippet`	The passage the answer draws on.

Render these next to the answer so a person can click through and verify. A score of null means a selected chunk was not in the scored candidate pool — show the citation without a confidence number rather than implying zero relevance.

Confidence from score buckets

Turn the citation score into a plain-language confidence badge:

Bucket	Score range	Suggested label
High	`≥ 0.7`	High confidence
Medium	`0.4 – 0.7`	Medium confidence
Low	`< 0.4`	Low confidence

Pair the bucket with meta.grounded for an honest indicator — a high similarity score with an unsupported grounding verdict should not be shown as high confidence.

The `grounded` verdict

meta.grounded answers a different question than the citation score: is the answer actually true to the cited sources?

Value	Meaning
`supported`	The answer is backed by the retrieved chunks.
`partial`	Some of the answer is supported; some is not.
`unsupported`	The answer is not backed by the chunks.
`null`	There were no documents to check against.

meta.grounded_score is the fraction of the answer that is supported. Use grounded, not just the citation score, to drive your confidence indicator — it reflects faithfulness, not mere lexical similarity.

Verify your result

Verify: Your UI shows label, page, and snippet for every citation.
Verify: The confidence badge combines the score bucket with meta.grounded.
Verify: A strict-mode refusal renders as an honest “no information” state, not an error.
Verify: An unsupported verdict in open mode is surfaced as low confidence.

Common mistakes and fixes

Showing high confidence on an unsupported answer → always gate the badge on meta.grounded, not on the citation score alone.
Treating empty sources as an error → in strict mode it is a refusal. See Troubleshooting.
Dropping the snippet → the snippet is what makes an answer verifiable; keep it.

Capture quality signals with Rating answers.
See how grounding interacts with streaming in Streaming (SSE).
Tune retrieval strictness via score_threshold in Chatting.

Languages Ingesting documents