POST /chatbots/{id}/retrieval-preview runs that same search for a question you supply and returns the full account: the chunks that were selected, every candidate that was dropped, the reason for each drop, and the scores behind it.
Nothing is recorded. No conversation is started, no answer is generated, and no credits are used. Use it to test how article changes affect retrieval before you publish them, or to diagnose why a chatbot answered from the wrong article.
How the search works
Each stage narrows the candidates. Theoutcome on every candidate tells you which stage stopped it.
1
Search
Two searches run in parallel over the knowledge the chatbot can use: one by meaning (vector search) and one by keywords (full-text search). Their results are merged into up to 30 candidates, each with a
fused_score.2
Rerank
A reranking model scores every candidate against the question and keeps the top 20. Candidates outside the top 20 are dropped with outcome
below_rerank_cutoff.3
Remove near-duplicates
Chunks whose text is near-verbatim copies of a higher-ranked chunk are dropped with outcome
near_duplicate. Similarity is measured on overlapping five-word sequences across the whole chunk, and a chunk is dropped at 0.7 or above. duplicate_of names the chunk that was kept.4
Select for relevance and variety
The final five are chosen to be relevant without repeating each other in meaning. A chunk that scored higher than a selected chunk but was passed over because it said much the same thing gets outcome
diversity. Everything else gets lower_score.When there are 20 or fewer candidates, reranking is skipped, and so are the
near-duplicate and variety steps (
reranked is false). The top five by
fused_score are selected.Making a request
string
required
The question, up to 2,000 characters. It is searched exactly as written. In a
real conversation, a follow-up such as “and the lid?” is first rewritten into
a complete question, so write complete questions here.
string | null
Search only this folder and its sub-folders. This is what the chatbot does
when it narrows its own search to one folder.
string | null
Search only chunks in this language. Omit it to search all languages, as a
conversation does.
string | null
Search as if a visitor had just scanned this QR code: the chatbot’s own
knowledge plus the knowledge linked to the code and to its group. The code
(or its group) must send visitors to this chatbot and be active, as in a real
scan; otherwise it is ignored and
scan_applied is false.string | null
The same as
qr_code_id, for a product scanned through a GS1 Digital Link.string | null
The same as
qr_code_id, for an object.A QR group can’t be passed on its own. To test a group’s knowledge, pass the
id of any QR code in the group: the code brings its group’s knowledge with
it, plus anything linked to the code itself.
The response
array
required
The chunks the model would receive, in rank order.
array
required
Every other candidate, in the order the first search ranked them, with its
outcome: below_rerank_cutoff, near_duplicate, diversity or
lower_score.number | null
How relevant the reranking model judged the chunk to the question. Compare it
between chunks of the same response; the absolute value has no fixed meaning.
null when the chunk didn’t reach reranking or reranking was skipped.string
required
The exact knowledge text the model would read when the chatbot searches
automatically. Short selected chunks are joined by the sections either side of
them in the same article, so this can contain more than the selected chunks.
string | null
What the model receives when it runs its own follow-up search for the same
question. Each selected chunk is cut to its first 800 characters, so
anything later in a chunk is not visible this way.
boolean | null
true when the scan you passed sends visitors to this chatbot, so its
knowledge was searched. false when it was ignored. null when you passed no
scan.boolean
On each chunk:
true when the chunk was reached through the scan’s linked
knowledge rather than only the chatbot’s own. These chunks get a small
ranking boost.string | null
When the scan links two or more folders and the selected chunks come from
more than one of them, the note the model reads above the results. It names
the folders and tells the model to ask which one the visitor means if they
are separate things (different machines, rooms or products) and the question
doesn’t make it clear. Each source in
served_context then carries
folder="…", and each result in tool_result carries [folder: …];
tool_result starts with the same note. null otherwise.Writing articles that retrieve well
- Keep repeated warnings short, or state them once. A long warning repeated at the top of every part of a section fills the start of each chunk. The parts then look alike to the search and compete for the same five places, and the model’s follow-up search (
tool_result) may show the warning without the steps after it. - A chunk is only dropped as a duplicate when nearly all of it is shared. Two chunks that open with the same warning but contain different steps are both kept. In testing, a chunk was dropped only when the shared text made up about 92% or more of it.
- Put the answer near the top of a section. It then lands early in a chunk, inside the first 800 characters.
Limits
Each preview runs a real search, so it is limited to 150 requests per minute per organization, on top of your organization’s general API rate limits. Over the limit, the API responds429 with retry_after in seconds. Requires the chatbots.view scope.