Reading a result

The response

{
  "vertical": "code",
  "routed": true,
  "mode": "hybrid",
  "total": 12,
  "results": [ … ],
  "facets": { … },
  "partial": false
}

Field	Meaning
vertical	The vertical actually queried. null if none applied.
routed	true when the router chose it, false when you named it.
mode	The mode actually used, which may differ from what you asked for if this deployment cannot serve it.
total	Matches.
results	The hits, up to limit.
facets	Only when facets=true.
partial	Read the next section.

partial is the field that changes the meaning

{ "total": 3, "partial": true }

When partial is true, at least one shard failed or timed out, and part of the corpus was not searched. The answer is short because a slice was unreachable — not because that is all there is.

This is said out loud rather than left to be inferred from total, because a short answer that is mistaken for a complete one is the most expensive failure this API can hand you: an agent concludes “there is nothing on this” and states it.

Handle it explicitly. Retry, or say the result is incomplete. Never treat a partial result as evidence of absence.

A hit

Always present:

Field	Meaning
id	Passage id, page:no. Pass to get_document, similar, related, corroborate, path.
url	Source URL.
host	Its host.
title	Document title.
vertical	Which vertical it lives in.
snippet	The passage text. Not a preview — usually the answer.
score	Relevance for this query. Comparable within a response, not across responses.
host_rank	Host trust prior, 0 to 1.
quality	Quality score.
fetched_at	Unix seconds, when we crawled it.
source	cc (bulk) or delta (freshly crawled).
story_id	The near-duplicate cluster this passage belongs to.

Present when they apply:

Field	Meaning
group_size	With collapse: how many rows were folded into this one.
published_at	When the content claims it was published. Absent when the page declares nothing.
content_type	article, docs, qa, academic, …
authority	Publisher-authority class.
tld	Top-level domain.
word_count	Passage length.
safety	Safety classification.
topics	Topic tags.
centrality	Graph centrality — how central this passage is to the corpus.
community_id	Which graph community it sits in.
independent_sources	Distinct hosts asserting this story.
in_degree	Incoming graph edges.

Absent means “not known for this passage”, not “zero”. A missing published_at means the page did not declare a date — which is also why published_from silently drops such pages.

The four fields that do work for you

• independent_sources — how many distinct hosts assert this. One echoed rumour and one independently reported fact are indistinguishable in a result list and distinguishable here. Filter on it with min_independent_sources.
• story_id and group_size — with collapse=story, one row per cluster and a count of what was folded in. This is what stops you reading the same wire copy five times.
• centrality — position in the corpus graph rather than match to your query. Sort by it to read the central sources in a field first.
• host_rank and quality — whether a source is worth reading, decided before you read it.

Using these is what makes a call to this API cheaper than the same call to a generic one. They cost nothing extra; they are already computed.

score

Comparable within one response and not between responses. It ranks; it does not measure. Do not threshold on an absolute value — a score of 0.4 in a sparse result set may be the best thing in the corpus, and 0.9 in a dense one may be the fifth-best paraphrase of the same sentence.

If you want a quality floor, use min_quality or min_host_rank, which mean the same thing every time.

total versus limit

total is the match count; results is capped by limit (default 10). To get the count without the results, ask for limit=0 — it costs one request and returns no hits.

Next

• Filters and sorting — filtering on these fields.
• The Coverage Graph — where the graph fields come from.
• Errors — when there is no response at all.