---
title: "Rerank"
method: POST
path: "/models/rerank"
tags: ["Models"]
---

# Rerank

`POST /models/rerank`

Reranks the provided documents, according to the provided query.

The results will be sorted by descending order of relevance. For each document, the index and the score will be returned. The index is relative to the documents array that was passed in. The score is the query-document relevancy determined by the reranker model. The results will be returned in descending order of relevance.

Organizations will, by default, have a ratelimit of `2,500,000` bytes-per-minute and 1000 QPM. Ratelimits are refreshed every 15 seconds. If this is exceeded, requests will be throttled into `latency: "slow"` mode, up to `20,000,000` bytes-per-minute. If even this is exceeded, you will get a `429` error. To request higher ratelimits, please contact [founders@zeroentropy.dev](mailto:founders@zeroentropy.dev) or message us on [Discord](https://go.zeroentropy.dev/discord) or [Slack](https://go.zeroentropy.dev/slack)!

## Request body

- RerankRequest
  - `model` string, required — The model ID to use for reranking. Options are: ["zerank-2", "zerank-1", "zerank-1-small"]
  - `query` string, required — The query to rerank the documents by.
  - `top_n` integer, nullable — If provided, then only the top `n` documents will be returned in the results array. Otherwise, `n` will be the length of the provided documents array.
  - `documents` string[], required — The list of documents to rerank. Each document is a string.
  - `latency` 'fast' | 'slow', nullable — Whether the call will be inferenced "fast" or "slow". RateLimits for slow API calls are orders of magnitude higher, but you can expect >10 second latency. Fast inferences are guaranteed subsecond, but rate limits are lower. If not specified, first a "fast" call will be attempted, but if you have exceeded your fast rate limit, then a slow call will be executed. If explicitly set to "fast", then 429 will be returned if it cannot be executed fast.

## Response `200`

Successful Response

- RerankResponse
  - `results` RerankResult[], required — The results, ordered by descending order of relevance to the query.
    - `index` integer, required — The index of this document, relative to the original document array passed into the request.
    - `relevance_score` number, required — The relevance score between this document and the query. This number will range between 0.0 and 1.0. This score is dependent on only the query and the scored document; other documents do not affect this score. This value is intended to be deterministic, but it may vary slightly due to floating point error.
  - `total_bytes` integer, required — The total number of bytes in the request. This is used for ratelimiting.
  - `total_tokens` integer, required — The total number of tokens in the request. This is used for billing.
  - `actual_latency_mode` 'fast' | 'slow', required — The type of inference actually used. If `auto` is requested, then `fast` will be used by default, with `slow` as a fallback if your ratelimit is exceeded. Else, this field will be identical to the requested latency mode.
  - `e2e_latency` number, required — The total time, in seconds, between rerank request received and rerank response returned. Client latency should equal `e2e_latency` + your ping to ZeroEntropy's API.
  - `inference_latency` number, required — The time, in seconds, to actually inference the request. If this is significantly lower than `e2e_latency`, this is likely due to ratelimiting. Please request a higher ratelimit at [founders@zeroentropy.dev](mailto:founders@zeroentropy.dev) or message us on [Discord](https://go.zeroentropy.dev/discord) or [Slack](https://go.zeroentropy.dev/slack)!

## Other responses

- `404` — Not Found
- `422` — Validation Error

## Changes

- **2026-01-21** `b5badb138367` — 5 info
  - added the required property `actual_latency_mode` to the response with the `200` status
  - added the required property `e2e_latency` to the response with the `200` status
  - added the required property `inference_latency` to the response with the `200` status
  - added the required property `total_bytes` to the response with the `200` status
  - …1 more
- **2025-11-24** `c95681b13dc5` — 1 breaking, 2 info
  - the request property `model` became required
  - added the new optional request property `latency`
  - the `model` request property default value `default` was removed
- **2025-07-08** `bd2f55f423e0` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zeroentropy-ai/apis/zeroentropy-api/changes/models/rerank/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)