---
title: "Top Snippets"
method: POST
path: "/queries/top-snippets"
tags: ["Queries"]
---

# Top Snippets

`POST /queries/top-snippets`

Get the top K snippets that match the given query.

You may choose between coarse and precise snippets. Precise snippets will average ~200 characters, while coarse snippets will average ~2000 characters. The default is coarse snippets. Use the `precise_responses` parameter to adjust.

## Request body

- TopSnippetsRequest
  - `collection_name` string, required — The name of the collection.
  - `query` string, required — The natural language query to search with. This cannot exceed 4096 characters (A single UTF-8 codepoint, is considered to be 1 character).
  - `k` integer, required — The number of snippets to return. If there are not enough snippets matching your filters, then fewer may be returned. This number must be between 1 and 128, inclusive.
  - `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).
  - `filter` StrJson
  - `precise_responses` boolean — Enable precise responses. Precise responses will have higher latency, but provide much more precise snippets. When `precise_responses` is set to `true`, the responses will average 200 characters. If set to `false`, the responses will average 2000 characters. The default is `false`.
  - `include_document_metadata` boolean — If true, the `document_results` returns will additionally contain document metadata. This is false by default, as returning metadata can add overhead if the amount of data to return is large.

## Response `200`

Successful Response

- TopSnippetsResponse
  - `results` SnippetResponse[], required — The array of snippets returned by this endpoint. Each snippet result refers to a particular document path, and index range. Note that all documents, regardless of filetype, are converted into `UTF-8`-encoded strings. The `start_index` and `end_index` of a snippet refer to the range of characters in that string, that have been matched by this snippet.
    - `path` string, required — The path of the document that this snippet comes from.
    - `start_index` integer, required — The start index of this snippet.
    - `end_index` integer, required — The end index of this snippet.
    - `page_span` integer[], required — The range of page indices spanned by this snippet, as a 2-tuple of integers. Inclusive on the first page_index and exclusive on the second page_index.
    - `content` string, required — The full string content of this snippet.
    - `score` number, required — The relevancy score assigned to this snippet.
  - `document_results` DocumentRetrievalResponse[], required — The array of associated document information. Note how each snippet 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 snippet 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

- **2025-07-08** `bd2f55f423e0` — 1 warning, 2 info
  - removed the request property `latency_mode`
  - added the new optional request property `reranker`
  - response property `results/items/content` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`
- **2025-06-03** `6d4d2509d6d6` — 2 info
  - added the new optional request property `include_document_metadata`
  - added the required property `document_results` 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-snippets/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)