Query All Collections - v3
Search every active collection in the environment of your API key and get back one ranked list. Captain lists the collections itself, runs each search at the same time, then reranks all candidates together in one pass, so results[].score is comparable across collections. Each result names its collection.
collections summarises every searched collection with its hits and best top_score, which answers which collections hold information on a topic. A collection whose search fails is reported there and the rest still return. The whole request is one query and bills once.
Up to 500 collections are searched, the most recently created first. Above that, or when the time budget runs out before a collection is reached, scope.not_searched counts the rest and a warning names the gap. exclude_collections leaves collections out. To query named collections with separate ranked lists, use Batch Query.
See Query Every Collection for the full guide.
Request
This endpoint expects an object.
>=1 characterNatural language search query. Must not be empty.
Metadata-based ranking. Each clause RETRIEVES matching chunks (its own filtered retrieval leg, fused with the vector and keyword legs) and MULTIPLIES their fused score by weight. With rerank off the boosted order is final. With rerank on, boosts shape the rerank pool and the reranker decides the final order unless a clause sets reserve. Boosted results report “metadata” in match_sources and carry a boost record; the clauses are echoed on the response with match counts. Not applied on collections containing image, video, or audio files (a warning is returned).
Layout roles to exclude from results (CAP-648). Allowed values: body, table, heading, page_header, page_footer, footnote, figure. Unknown values are a 400. Exclusion happens at retrieval time, BEFORE reranking. Chunks with no chunk_type label (legacy rows, txt/media content, 75+ page parses) always pass: null never matches an exclusion.
Names of collections to leave out of the search. Names that do not exist are ignored.
Optional expansions for v3 query results. Leave expensive context off unless the caller needs it.
1-100Defaults to 101-100Cap on how many chunks any single document may occupy in results. Ranking is unchanged: the same ranked chunks come back, minus a document’s surplus beyond the cap, backfilled with the next best chunks from other documents so limit results still come back whenever the ranked pool has them. Omitted (the default) applies no cap. The two numbers compose: limit = N x K returns up to N documents with up to K chunks each, in document-rank order, and each result’s document object (include.document, on by default) carries the document’s id, filename, and source. For the five most relevant documents, send limit: 5 with max_chunks_per_document: 1.
outgoingoutgoingincomingbothtrueRerank the merged candidates from every collection together, so scores are comparable across collections. On by default here. With false, results are interleaved by each collection’s own rank and scores are not comparable across collections. Object form tunes it: {enabled, candidate_limit, model}. By default every candidate is reranked: each collection’s top max(10, limit) hits (fewer when many collections share the request’s 4000-result retrieval budget, never fewer than 10), up to 2000 in all (an explicit candidate_limit is capped at 200). The gemini models score at most 50.
0-1Defaults to 0.5Balance between semantic and keyword retrieval. Captain searches both ways at once: keyword (sparse, BM25) matches the words in the query, semantic (dense vector) matches its meaning. 0.0 is keyword only, 1.0 is semantic only, and 0.5 (the default) weighs them equally. Lower it for corpora full of exact terms such as part numbers or error codes; raise it when callers phrase questions in their own words. Between the endpoints both searches run, so a result found only by the down-weighted side still appears, just lower. The endpoints skip the other search entirely: 0.0 also skips embedding the query, making it the fastest option, though queries using boost and collections holding images, video, or audio keep vector search running.
1-100DeprecatedDeprecated alias for limit, accepted so v2 callers migrating to v3 are not silently given the default page size. Use limit.
Response
Successful Response
One entry per searched collection, best top_score first, then collections without hits, then failed ones.
Wall-clock time for the whole request, in milliseconds.
Reranking status for the query response.
One ranked list across every searched collection, best first, at most limit long. With rerank on (the default here), scores come from one reranker pass over the merged candidates, so they are comparable across collections.
Number of results in this response (len(results)).
Id of this query in your history. The whole request is one query: it is stored and billed once.
0.5Errors
{
"query": "dashboards",
"exclude_collections": [
"archive"
],
"limit": 3
}{
"collections": [
{
"collection": "product-docs",
"hits": 3,
"in_results": 2,
"status": "succeeded",
"error": null,
"top_score": 0.8125
},
{
"collection": "support-tickets",
"hits": 3,
"in_results": 1,
"status": "succeeded",
"error": null,
"top_score": 0.6406
},
{
"collection": "hr-policies",
"hits": 3,
"in_results": 0,
"status": "succeeded",
"error": null,
"top_score": 0.0391
},
{
"collection": "invoices",
"hits": 0,
"in_results": 0,
"status": "failed",
"error": {
"message": "The query did not finish in time (collections[3]: 'invoices')",
"status_code": 504,
"detail": null,
"retry_after_seconds": null
},
"top_score": null
}
],
"execution_time_ms": 1840,
"limit": 3,
"query": "dashboards",
"request_id": "req_1794480000_0a1b2c3d",
"rerank": {
"used": true,
"reason": "requested",
"model": "voyage-rerank-2.5",
"candidate_limit": 9,
"fallback": null
},
"results": [
{
"chunk_id": "3f9a1c2e7b8d4e5f9a0b1c2d3e4f5a6b:3",
"collection": "product-docs",
"score": 0.8125,
"text": "Dashboards show each collection's query volume and latency. Open Dashboards from the sidebar to pin a chart.",
"document": {
"id": "3f9a1c2e7b8d4e5f9a0b1c2d3e4f5a6b",
"filename": "dashboards-guide.pdf",
"source": {
"type": "upload",
"uri": null,
"mime_type": "application/pdf"
}
},
"location": {
"page_start": 2,
"page_end": 2,
"chunk_index": 3
},
"match_sources": [
"content_embedding",
"keyword"
],
"modality": "pdf",
"rerank_score": 0.8125
},
{
"chunk_id": "8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e:0",
"collection": "support-tickets",
"score": 0.6406,
"text": "Customer asked how to share a dashboard with a teammate. Resolved by sending the share link.",
"document": {
"id": "8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e",
"filename": "ticket-1000000000.pdf",
"source": {
"type": "upload",
"uri": null,
"mime_type": "application/pdf"
}
},
"location": {
"page_start": 2,
"page_end": 2,
"chunk_index": 3
},
"match_sources": [
"content_embedding",
"keyword"
],
"modality": "pdf",
"rerank_score": 0.6406
},
{
"chunk_id": "3f9a1c2e7b8d4e5f9a0b1c2d3e4f5a6b:7",
"collection": "product-docs",
"score": 0.5938,
"text": "Each dashboard chart can be filtered by environment and date range.",
"document": {
"id": "3f9a1c2e7b8d4e5f9a0b1c2d3e4f5a6b",
"filename": "dashboards-guide.pdf",
"source": {
"type": "upload",
"uri": null,
"mime_type": "application/pdf"
}
},
"location": {
"page_start": 2,
"page_end": 2,
"chunk_index": 3
},
"match_sources": [
"content_embedding",
"keyword"
],
"modality": "pdf",
"rerank_score": 0.5938
}
],
"scope": {
"environment": "production",
"failed": 1,
"searched": 4,
"excluded": 1,
"not_searched": 0,
"type": "all"
},
"total_results": 3,
"exclude_chunk_types": [],
"query_id": "6f1e2d3c-4b5a-4968-8776-655443322110",
"semantic_ratio": 0.5,
"warnings": []
}