API ReferenceQuery

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.

rerankbooleanOptionalDefaults to false
Whether to request reranking. Multimodal collections may apply reranking even when this is false.
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.

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.

Errors

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