---
title: "Query"
method: POST
path: "/v3/collections/{collection_name}/query"
tags: ["file-search"]
---

# Query

`POST /v3/collections/{collection_name}/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](/guides/advanced-querying) for the full filter reference.

## Path parameters

- `collection_name` string, required

## Request body

- QueryRequestV3 — Request body for v3 File Search.
  - `query` string, required — Natural-language search query.
  - `limit` integer — Maximum number of ranked chunks to return.
  - `filter` QueryRequestV3Filter — 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](/guides/advanced-querying) for more.
  - `rerank` union — 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.
    - boolean
    - RerankOptions — Object form of the `rerank` parameter. The boolean form stays valid: `true` is equivalent to sending this object with every field at its default.
      - `enabled` boolean — Whether to rerank. Sending the object without this field means enabled — the object form exists to tune reranking.
      - `candidate_limit` integer, nullable — How many fused retrieval candidates are fetched and reranked before the top `limit` results are returned. Defaults to `limit` x 3 (the measured configuration). Must be >= `limit`; capped at 200. Larger pools can lift recall on corpora with many near-duplicate documents, at the cost of rerank latency.
      - `model` string, nullable — Reranker model. One of `voyage-rerank-2.5` (default) or `gemini-2.5-flash`; the family aliases `voyage` and `gemini` are accepted. Unknown values return a 400 listing the allowed set.
  - `include` QueryIncludeV3 — Optional expansions for v3 query results. Leave expensive context off unless the caller needs it.
    - `document` boolean — Include the parent document object for each returned chunk.
    - `metadata` boolean — Include Captain-generated retrieval metadata and application-supplied chunk metadata.
    - `regions` boolean — Include extracted layout regions, including bounding boxes when available.
    - `relations` boolean — Include graph relations connected to each returned chunk.
    - `related_chunks` boolean — Include linked chunks for returned relations.
    - `neighboring_chunks` boolean — Include the chunk immediately before and after each result in the source file.
    - `document_metadata` boolean
    - `archived` boolean — Include chunks archived by a sync `archive` deletion policy. Archived content is excluded from search by default; set true to surface it.
  - `relation_types` string[], 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_types` QueryRequestV3ExcludeChunkTypesItems[], 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.
  - `boost` BoostClauseV3[], nullable — 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.
    - `field` string, nullable — Required with `eq` or `in`; omit it for a `chunk_ids` rule. One of your own custom_metadata keys, the same keys `filter` accepts. Anything filterable is boostable, with no re-indexing. Captain's internal attributes (file_id, job_id, chunk_index and similar) return a 400.
    - `eq` union — Requires `field`. Boost chunks whose `field` equals this value. Strings, numbers, and booleans are supported. A list-valued field matches when any element equals it. Use `in` instead for several values.
      - string
      - integer
      - number, double
      - boolean
    - `in` BoostClauseV3InItems[], nullable — Requires `field`. Boost chunks whose `field` matches any of these values, up to 50. Use it for one key with several acceptable values, and for list-valued metadata.
      - union
        - string
        - integer
        - number, double
        - boolean
    - `chunk_ids` string[], nullable — Use instead of `field`/`eq`/`in` to boost specific chunks, up to 100. Accepts a `chunk_id` from a previous response, or `document_id:chunk_index`, which keeps resolving after the document is re-indexed. Use it to keep a follow-up question anchored to passages an earlier answer cited.
    - `weight` number, double, required — Required. Multiplier on the matching chunk's retrieval score, 0.2 to 5.0. The rule's retrieval pass is what makes a chunk appear; the weight decides where it lands. 1.5 to 2.0 is a good default and is usually enough to lift a tagged chunk to the top. Use 3.0 to 5.0 when boosted chunks compete with each other, or when a rule matches many chunks. Below 1.0 demotes, and only reorders chunks the query already found. When several rules match the same chunk their weights multiply, capped at 5.0.
    - `reserve` integer — With reranking on, guarantee this many of this rule's chunks a place on the page, chosen by reranker order. Reranking runs after boosting and can otherwise drop a boosted chunk whose text does not resemble the query. 0 (default) leaves the reranker's judgement in charge. The sum across all boost rules cannot exceed `limit`.
  - `semantic_ratio` number, 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 `200`

Query response.

- QueryResponseV3 — Response body for v3 File Search.
  - `query` string, required — Echo of the submitted query.
  - `results` FileSearchResultV3[], required — Retrieved source chunks sorted by final retrieval score.
    - `chunk_id` string, required — Stable identifier for the retrieved chunk. Chunk IDs include the parent document identifier and chunk index.
    - `score` number, double, required — Final retrieval score used to rank the result. Use it to compare results within the same response, not across unrelated collections.
    - `text` string, required — Retrieved chunk text.
    - `modality` 'text' | 'pdf' | 'document' | 'image' | 'audio' | 'video' | 'spreadsheet' | 'unknown' — Indexed content type that matched the query.
    - `match_sources` FileSearchResultV3MatchSourcesItems[] — Retrieval signals that contributed to the match, such as `content_embedding`, `keyword`, `ocr`, `table`, `transcript`, `metadata`, or `summary`.
    - `document` FileSearchDocumentV3 — Parent document for a returned chunk.
      - `id` string, nullable — Document identifier.
      - `filename` string, nullable — Original or indexed filename.
      - `source` FileSearchSourceV3 — Original source information for an indexed file.
        - `type` string, nullable — Source kind, such as uploaded file, cloud object, URL, or Captain-managed file.
        - `uri` string, nullable — Original file URI or Captain-managed URI.
        - `mime_type` string, nullable — MIME type when known.
      - `custom_metadata` object, nullable
    - `location` FileSearchLocationFromV3
      - `page_start` integer, nullable
      - `page_end` integer, nullable
      - `chunk_index` integer, nullable
      - `parent_chunk_index` integer, nullable
      - `start_seconds` number, double, nullable
      - `end_seconds` number, double, nullable
      - `sheet_name` string, nullable
      - `row_start` integer, nullable
      - `row_end` integer, nullable
      - `col_start` integer, nullable
      - `col_end` integer, nullable
    - `media` FileSearchMediaV3 — Media-specific context for audio and video chunks.
      - `transcript` string, nullable — Transcript text associated with the returned media segment.
    - `regions` FileSearchRegionFromV3[], nullable — Extracted layout regions when `include.regions` is enabled. Regions can represent OCR text, form fields, headings, tables, charts, or image areas.
      - `type` string, nullable — Region category, such as `text`, `title`, `section_header`, `key_value`, `table`, `figure`, `chart`, or `image`. Regions of type `figure`, `chart`, or `image` also carry a cropped `image_url` (a visual citation).
      - `text` string, nullable
      - `page` integer, nullable
      - `bbox` object, nullable
      - `confidence` string, nullable
      - `image_url` string, nullable — Short-lived presigned URL to a cropped image of the region (a visual citation), returned for `figure`, `chart`, and `image` regions when `include.regions` is true. Null for text regions and for documents indexed before figure cropping was enabled. Fetch promptly — the link expires within minutes.
      - `description` string, nullable
    - `metadata` FileSearchResultV3Metadata — Captain-generated retrieval, ranking, source location, and indexed content metadata.
    - `custom_metadata` FileSearchResultV3CustomMetadata — Application-supplied chunk metadata from indexing or chunk metadata update endpoints.
    - `rerank_score` number, double, nullable — Score assigned by the reranker for this result when reranking is applied.
    - `relations` ChunkRelationFromV3[], nullable — Graph edges connected to the retrieved chunk when relation context is requested.
      - `relation_id` string, required
      - `source_chunk_id` string, required
      - `target_chunk_id` string, required
      - `target_document_id` string, nullable
      - `target_status` 'found' | 'missing' | 'unknown'
      - `relation_type` string, required
      - `metadata` ChunkRelationFromV3Metadata
      - `created_at` string, nullable
      - `updated_at` string, nullable
    - `related_chunks` RelatedChunkV3[], nullable — Linked chunks returned with relation context, including their text, location, and metadata when available.
      - `chunk_id` string, required — Related chunk identifier.
      - `document_id` string, nullable — Parent document identifier for the related chunk.
      - `text` string, nullable — Related chunk text when included.
      - `location` FileSearchLocationFromV3
        - `page_start` integer, nullable
        - `page_end` integer, nullable
        - `chunk_index` integer, nullable
        - `parent_chunk_index` integer, nullable
        - `start_seconds` number, double, nullable
        - `end_seconds` number, double, nullable
        - `sheet_name` string, nullable
        - `row_start` integer, nullable
        - `row_end` integer, nullable
        - `col_start` integer, nullable
        - `col_end` integer, nullable
      - `metadata` RelatedChunkV3Metadata — Metadata associated with the related chunk.
      - `chunk_type` 'body' | 'table' | 'heading' | 'page_header' | 'page_footer' | 'footnote' | 'figure' — Layout role of this chunk, classified from the parser's block structure at indexing time: body, table, heading, page_header, page_footer, footnote, or figure. Null when the chunk has no label: content indexed before chunk types shipped, plain-text and media content, or regions the parser returned without block structure. Treat unknown future values as additive. Present on related and neighboring chunks as well.
    - `neighboring_chunks` ChunkNeighborsV3 — The chunks immediately before and after a result in the source file, returned when `include.neighbors` is enabled.
      - `prev` RelatedChunkV3 — Chunk linked to a search result through a requested relation.
        - `chunk_id` string, required — Related chunk identifier.
        - `document_id` string, nullable — Parent document identifier for the related chunk.
        - `text` string, nullable — Related chunk text when included.
        - `location` FileSearchLocationFromV3
          - `page_start` integer, nullable
          - `page_end` integer, nullable
          - `chunk_index` integer, nullable
          - `parent_chunk_index` integer, nullable
          - `start_seconds` number, double, nullable
          - `end_seconds` number, double, nullable
          - `sheet_name` string, nullable
          - `row_start` integer, nullable
          - `row_end` integer, nullable
          - `col_start` integer, nullable
          - `col_end` integer, nullable
        - `metadata` RelatedChunkV3Metadata — Metadata associated with the related chunk.
        - `chunk_type` 'body' | 'table' | 'heading' | 'page_header' | 'page_footer' | 'footnote' | 'figure' — Layout role of this chunk, classified from the parser's block structure at indexing time: body, table, heading, page_header, page_footer, footnote, or figure. Null when the chunk has no label: content indexed before chunk types shipped, plain-text and media content, or regions the parser returned without block structure. Treat unknown future values as additive. Present on related and neighboring chunks as well.
      - `next` RelatedChunkV3 — Chunk linked to a search result through a requested relation.
        - `chunk_id` string, required — Related chunk identifier.
        - `document_id` string, nullable — Parent document identifier for the related chunk.
        - `text` string, nullable — Related chunk text when included.
        - `location` FileSearchLocationFromV3
          - `page_start` integer, nullable
          - `page_end` integer, nullable
          - `chunk_index` integer, nullable
          - `parent_chunk_index` integer, nullable
          - `start_seconds` number, double, nullable
          - `end_seconds` number, double, nullable
          - `sheet_name` string, nullable
          - `row_start` integer, nullable
          - `row_end` integer, nullable
          - `col_start` integer, nullable
          - `col_end` integer, nullable
        - `metadata` RelatedChunkV3Metadata — Metadata associated with the related chunk.
        - `chunk_type` 'body' | 'table' | 'heading' | 'page_header' | 'page_footer' | 'footnote' | 'figure' — Layout role of this chunk, classified from the parser's block structure at indexing time: body, table, heading, page_header, page_footer, footnote, or figure. Null when the chunk has no label: content indexed before chunk types shipped, plain-text and media content, or regions the parser returned without block structure. Treat unknown future values as additive. Present on related and neighboring chunks as well.
    - `chunk_type` 'body' | 'table' | 'heading' | 'page_header' | 'page_footer' | 'footnote' | 'figure' — Layout role of this chunk, classified from the parser's block structure at indexing time: body, table, heading, page_header, page_footer, footnote, or figure. Null when the chunk has no label: content indexed before chunk types shipped, plain-text and media content, or regions the parser returned without block structure. Treat unknown future values as additive.
    - `boost` ResultBoostV3 — Why a result was boosted, and where it stood before the boost.
      - `multiplier` number, double, required — The combined weight applied to this chunk, capped at 5.0.
      - `clauses` integer[] — Which boost rules matched, as positions in the request's `boost` array.
      - `pre_boost_rank` integer, nullable — This chunk's retrieval rank before the boost, 1-based.
      - `pre_boost_score` number, double, nullable — This chunk's retrieval score before the boost.
      - `reserved` boolean — True when `reserve` placed this result on the page rather than its score.
  - `total_results` integer, required — Number of results returned in this response.
  - `limit` integer, required — Result limit applied to the request.
  - `rerank` QueryRerankV3, required — Reranking status for the query response.
    - `used` boolean, required — Whether reranking was applied.
    - `reason` 'requested' | 'disabled' | 'required_for_multimodal' | 'default_for_multimodal', required — Why reranking was applied or skipped.
    - `model` string, nullable — The reranker model that ran. Null when reranking was not applied.
    - `candidate_limit` integer, nullable — The candidate pool size that was reranked. Null when reranking was not applied.
  - `warnings` string[] — Non-fatal notices about the request or response, such as forced reranking for multimodal collections.
  - `execution_time_ms` integer, nullable — Server-side execution time in milliseconds.
  - `request_id` string, nullable — Request identifier for support and trace lookup.
  - `exclude_chunk_types` QueryResponseV3ExcludeChunkTypesItems[] — The layout roles this query excluded, echoed back so a caller can confirm what the server applied. Empty when none were requested.
  - `boost` BoostAppliedV3[] — The boost rules this query applied, each with `matched`, `in_pool`, and `on_page` counts. Always present; empty when no boost was sent.
    - `field` string, nullable — The metadata key this rule targeted.
    - `eq` union — The value this rule matched on.
      - string
      - integer
      - number, double
      - boolean
    - `in` BoostAppliedV3InItems[], nullable — The values this rule matched on.
      - union
        - string
        - integer
        - number, double
        - boolean
    - `chunk_ids` string[], nullable — The chunks this rule targeted.
    - `weight` number, double, required — The multiplier this rule applied.
    - `reserve` integer — Page slots this rule guaranteed. 0 means the reranker decided.
    - `matched` integer — Retrieved chunks this rule matched.
    - `in_pool` integer — Matched chunks that reached reranking. Equals `matched` when reranking is off.
    - `on_page` integer — Matched chunks in the results returned.
    - `applied` boolean — False when boosts were skipped; a warning explains why.
  - `semantic_ratio` number, double — The semantic/keyword balance applied to this query. Always present; 0.5 when the request did not set one.

## Other responses

- `400` — Invalid metadata filter.
- `401` — Missing or invalid authentication.
- `403` — API key cannot query this collection.
- `404` — Collection not found.

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runcaptain/api-reference/revisions/fe4649e3f4aa/schema)