POST/v1/search/multiREAD

Multi-collection search

Search several collections at once and merge the results globally.

Fans the query out to every listed collection and merges the results into one globally-ranked list.

All named collections must share the same dimension and metric. Scores from different corpora aren't comparable, and merging them would silently corrupt the ranking — the contract enforces this compatibility check before running any search. BM25 reranking and graph reranking are not applied here (same reason: term-frequency and graph scores aren't comparable across independent collections either).

Request body

querynumber[]required

Query vector. Must match the shared dimension of every listed collection.

kintegerrequired

Number of global top-k results to return, after merging.

collectionsstring[]required

One or more collection names to search.

decay_half_life_secsintegeroptional

Recency decay half-life in seconds, applied per-collection before the results are merged.

metadata_filterobjectoptional

Metadata predicate applied per-collection after vector search, same shape as Vector search's.

Response fields

resultsarrayrequired

Global top-k hits, sorted by score ascending (smaller = closer — Squared L2 distance to the query).

results[].collectionstringrequired

Which collection this hit came from.

results[].idintegerrequired

The record's id within its collection.

results[].scorenumberrequired

Squared L2 distance to the query. Smaller is closer.

results[].decay_factornumberoptional

Applied decay factor. Present only when decay_half_life_secs was set.

results[].age_secsintegeroptional

Record age in seconds. Present only when decay is active.

collections_searchedstring[]required

Every collection name included in this query.

partial_failuresarrayoptional

Present only when at least one collection's search failed after dimension/metric compatibility was confirmed — one collection erroring at query time doesn't fail the whole request.

Errors

Status	`code`	Meaning
`400`	`validation_error`	Malformed request, or the listed collections don't share a dimension/metric.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`forbidden`	The key's scope doesn't include `read_only`.
`404`	`collection_not_found`	One of the listed collections doesn't exist.

Related endpoints

Vector search — single-collection search with the full parameter set (decay, reranking, graph rerank)