---
title: "Top Documents"
method: POST
path: "/queries/top-documents"
tags: ["Queries"]
---

# Top Documents

`POST /queries/top-documents`

Get the top K documents that match the given query

## Request body

- TopDocumentsRequest
  - `collection_name` string, required — The name of the collection.
  - `query` string, nullable, required — The natural language query to search with. This cannot exceed 4096 UTF-8 bytes. If `null`, then the sort will be undefined. The purpose of `null` is to do faster metadata filter searches without care for relevancy. Cost per query is unchanged.
  - `k` integer, required — The number of documents to return. If there are not enough documents matching your filters, then fewer may be returned. This number must be between 1 and 2048, inclusive.
  - `filter` StrJson
  - `include_metadata` boolean — Whether or not to include the metadata in the top documents response. If not provided, then the default will be `False`.
  - `reranker` string, nullable — The reranker to use after initial retrieval. The default is `null`. You can find available model ids along with more information at [/models/rerank](/api-reference/models/rerank).
  - `latency_mode` 'low' | 'high' — This option selects between our two latency modes. The higher latency mode takes longer, but can allow for more accurate responses. If desired, test both to customize your search experience for your particular use-case, or use the default of "low" and only swap if you need an additional improvement in search result quality.

## Response `200`

Successful Response

- TopDocumentsResponse
  - `results` DocumentRetrievalResponse[], required
    - `path` string, required — The path of the document.
    - `score` number, required — The relevancy score assigned to this document.
    - `metadata` DocumentMetadataJson, required
    - `file_url` string, required — A URL to the document data, which can be used to download the raw document content or to display the document in frontend applications. NOTE: If a `/documents/update-document` call returned a new document id, then this url will be invalidated and must be retrieved again.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `422` — Validation Error

## Changes

- **2025-11-24** `c95681b13dc5` — 1 info
  - request property `query` list-of-types was widened by adding types `null` to media type `application/json`
- **2025-07-08** `bd2f55f423e0` — 1 info
  - added the new optional request property `reranker`
- **2025-06-03** `6d4d2509d6d6` — 1 info
  - added the required property `results/items/file_url` to the response with the `200` status
- **2025-01-27** `99a41bb73e43` — 1 info
  - added the new optional request property `latency_mode`
- **2025-01-18** `2140640e14f6` — 1 breaking
  - request property `filter/anyOf[#/components/schemas/StrJson]/` list-of-types was narrowed by removing types `array and string` from media type `application/json`

[Change history](https://skmtc.dev/zeroentropy-ai/apis/zeroentropy-api/changes/queries/top-documents/post.md)

---

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