Sign in
file-search

Query

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 for the full filter reference.

post/v3/collections/{collection_name}/query

Path parameters

collection_namestring required

Request body

querystring required

Natural-language search query.

limitinteger

Maximum number of ranked chunks to return.

filterQueryRequestV3Filter

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.

relation_typesstring[] nullable

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

relation_direction'outgoing' | 'incoming' | 'both'

Which graph edge direction to include for relation context.

exclude_chunk_typesQueryRequestV3ExcludeChunkTypesItems[] nullable

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.

semantic_rationumber double

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 required

Echo of the submitted query.

total_resultsinteger required

Number of results returned in this response.

limitinteger required

Result limit applied to the request.

warningsstring[]

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

execution_time_msinteger nullable

Server-side execution time in milliseconds.

request_idstring nullable

Request identifier for support and trace lookup.

exclude_chunk_typesQueryResponseV3ExcludeChunkTypesItems[]

The layout roles this query excluded, echoed back so a caller can confirm what the server applied. Empty when none were requested.

semantic_rationumber double

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

Changes