API ReferenceQueries

Query - v3

Search indexed files and return source chunks with optional document, metadata, region (bounding boxes), relation, and related chunk context. **Compared with v2:** this response uses `results[].text`, supports explicit include controls, and returns structured rerank details. **Filter keys are top-level field names.** Never nest them under `metadata` or `custom_metadata`. Use `{"policy_area": "payments"}`, not `{"custom_metadata": {"policy_area": "payments"}}`. Operators are `$`-prefixed (`$gte`, not `gte`). See the [Advanced Querying guide](/guides/advanced-querying) for the full filter reference.

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.
querystringRequired

Natural-language search query.

limitintegerOptional1-100Defaults to 10
Maximum number of ranked chunks to return.
filterobject or nullOptional

Document metadata filter expression. Keys are top-level field names, never nested under metadata or custom_metadata. A bare value is an implicit \$eq ({"policy_area": "payments"}). Supported operators: \$eq (=), \$ne (≠), \$gt (>), \$gte (≥), \$lt (<), \$lte (≤), \$in, \$nin, and the logical \$and and \$or. \$in and \$nin take a list; every other operator takes a scalar. Max nesting depth is 10. To scope a query to specific documents, filter on file_id with \$in. See the Advanced Querying guide for more.

rerankboolean or objectOptionalDefaults to false

Rerank retrieved candidates before returning the top results (adds roughly 200 ms). Boolean form uses the defaults: voyage-rerank-2.5 over a pool of limit x 3 candidates. Object form tunes reranking — see RerankOptions. Multimodal collections default to reranking; an explicit false (or {"enabled": false}) opts out and returns a warning noting reduced cross-modal ranking quality.

includeobjectOptional
Controls which optional result objects are included in the response.
relation_typeslist of strings or nullOptional

Optional relation type filter when include.relations or include.related_chunks is enabled.

relation_directionenumOptionalDefaults to outgoing
Which graph edge direction to include for relation context.
exclude_chunk_typeslist of enums or nullOptional

Layout roles to drop from results: body, table, heading, page_header, page_footer, footnote, figure. Useful for removing repeated page furniture such as running headers and footnotes. Applied during retrieval, before reranking, so excluded chunks never occupy a result slot. Chunks with no layout label always pass. Unknown values return a 400.

boostlist of objects or nullOptional

Optional metadata-based ranking: a list of up to 10 boost rules, each naming some of your own custom_metadata and how much to favour the chunks carrying it. Use it when a chunk is the right answer but does not match the query’s wording, for example one a reviewer tagged as the answer to this question, or one your application already cited earlier in a conversation. Each rule both retrieves chunks carrying that metadata and multiplies their retrieval score by weight. With reranking on the reranker still decides the final order unless a rule sets reserve. Omit the field entirely and retrieval is unchanged. See the Advanced Search guide for choosing a weight.

semantic_ratiodoubleOptional0-1Defaults to 0.5

Balance 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. See the Advanced Querying guide for more.

Response

Query response.
querystring
Echo of the submitted query.
resultslist of objects
Retrieved source chunks sorted by final retrieval score.
total_resultsinteger
Number of results returned in this response.
limitinteger
Result limit applied to the request.
rerankobject
Whether reranking was applied and why.
warningslist of stringsOptional

Non-fatal notices about the request or response, such as forced reranking for multimodal collections.

execution_time_msinteger or nullOptional

Server-side execution time in milliseconds.

request_idstring or nullOptional
Request identifier for support and trace lookup.
query_idstring or nullOptional

Id of this query in your history. Fetch it back with GET /v2/queries/{query_id}. Present when the query was stored (completed, non-streamed queries).

exclude_chunk_typeslist of enumsOptionalDefaults to []
The layout roles this query excluded, echoed back so a caller can confirm what the server applied. Empty when none were requested.
boostlist of objectsOptionalDefaults to []

The boost rules this query applied, each with matched, in_pool, and on_page counts. Always present; empty when no boost was sent.

semantic_ratiodoubleOptionalDefaults to 0.5

The semantic/keyword balance applied to this query. Always present; 0.5 when the request did not set one.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
© 2026 Captain