---
title: "Top Pages"
method: POST
path: "/queries/top-pages"
tags: ["Queries"]
---

# Top Pages

`POST /queries/top-pages`

Get the top K pages that match the given query

## Request body

- TopPagesRequest
  - `collection_name` string, required — The name of the collection.
  - `query` string, required — The natural language query to search with. This cannot exceed 4096 UTF-8 bytes.
  - `k` integer, required — The number of pages to return. If there are not enough pages matching your filters, then fewer may be returned. This number must be between 1 and 1024, inclusive.
  - `filter` StrJson
  - `include_content` boolean — If set to true, then the content of all pages will be returned.
  - `include_metadata` boolean — Whether or not to include the document metadata in the response. If not provided, then the default will be `False`.
  - `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

- TopPagesResponse
  - `results` PageRetrievalResponse[], required
    - `path` string, required — The path of the document that this page comes from.
    - `page_index` integer, required — The index of this page in the document. This field is 0-indexed. So, the 1st page has index 0, and the 2nd page has index 1.
    - `score` number, required — The relevancy score assigned to this page.
    - `content` string, nullable, required — The contents of this page. This property will be null when `include_content` is `false`, and a string when `include_content` is `true`.
    - `image_url` string, nullable, required — A URL to an image of the page. This field will only be provided if the document has finished parsing, and if it is a filetype that is capable of producing images (e.g. PDF, DOCX, PPT, etc). In all other cases, this field will be `null`. NOTE: If a `/documents/update-document` call returned a new document id, then this url will be invalidated and must be retrieved again.
  - `document_results` DocumentRetrievalResponse[], required — The array of associated document information. Note how each result page has an associated document path. After deduplicating the document paths, this array will contain document info for each document path that is referenced by at least one page result.
    - `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

- **2026-03-03** `cd86445a8ef0` — 2 info
  - added the new optional request property `include_metadata`
  - added the required property `document_results` to the response with the `200` status
- **2025-01-27** `99a41bb73e43` — 2 info
  - added the new optional request property `latency_mode`
  - added the required property `results/items/image_url` to the response with the `200` status
- **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-pages/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)