---
title: "Rerankers"
method: POST
path: "/rerank"
tags: ["Inference"]
---

# Rerankers

`POST /rerank`

Voyage reranker endpoint receives as input a query, a list of documents, and other arguments such as the model name, and returns a response containing the reranking results.

## Request body

- object
  - `query` string, required — The query as a string. The query can contain a maximum of 8,000 tokens for `rerank-2.5` and `rerank-2.5-lite`; 4,000 tokens for `rerank-2`; 2,000 tokens for `rerank-2-lite` and `rerank-1`; and 1,000 tokens for `rerank-lite-1`.
  - `documents` string[], required — The documents to be reranked as a list of strings. <ul> <li> The number of documents cannot exceed 1,000. </li> <li> The sum of the number of tokens in the query and the number of tokens in any single document cannot exceed 32,000 for `rerank-2.5` and `rerank-2.5-lite`; 16,000 for `rerank-2`; 8,000 for `rerank-2-lite` and `rerank-1`; and 4,000 for `rerank-lite-1`. </li> <li> The total number of tokens, defined as "the number of query tokens × the number of documents + sum of the number of tokens in all documents", cannot exceed 600K for `rerank-2.5`, `rerank-2.5-lite`, `rerank-2` and `rerank-2-lite`; and 300K for `rerank-1` and `rerank-lite-1`. Please see our <a href="https://docs.voyageai.com/docs/faq#what-is-the-total-number-of-tokens-for-the-rerankers">FAQ</a>. </li> </ul>
  - `model` string, required — Name of the model. Recommended options: `rerank-2.5`, `rerank-2.5-lite`.
  - `top_k` integer, nullable — The number of most relevant documents to return. If not specified, the reranking results of all documents will be returned.
  - `return_documents` boolean — Whether to return the documents in the response. Defaults to `false`. <ul> <li> If `false`, the API will return a list of {"index", "relevance_score"} where "index" refers to the index of a document within the input list. </li> <li> If `true`, the API will return a list of {"index", "document", "relevance_score"} where "document" is the corresponding document from the input list. </li> </ul>
  - `truncation` boolean — Whether to truncate the input to satisfy the "context length limit" on the query and the documents. Defaults to `true`. <ul> <li> If `true`, the query and documents will be truncated to fit within the context length limit, before processed by the reranker model. </li> <li> If `false`, an error will be raised when the query exceeds 8,000 tokens for `rerank-2.5` and `rerank-2.5-lite`; 4,000 tokens for `rerank-2`; 2,000 tokens `rerank-2-lite` and `rerank-1`; and 1,000 tokens for `rerank-lite-1`, or the sum of the number of tokens in the query and the number of tokens in any single document exceeds 32,000 for `rerank-2.5` and `rerank-2.5-lite`; 16,000 for `rerank-2`; 8,000 for `rerank-2-lite` and `rerank-1`; and 4,000 for `rerank-lite-1`. </li> </ul>

## Response `200`

Success

- RerankingObject
  - `object` string — The object type, which is always `list`.
  - `data` object[] — An array of the reranking results, sorted by the descending order of relevance scores.
    - `index` integer — The index of the document in the input list.
    - `relevance_score` number — The relevance score of the document with respect to the query.
    - `document` string — The document string. Only returned when return_documents is set to true.
  - `model` string — Name of the model.
  - `usage` object
    - `total_tokens` integer — The total number of tokens used for computing the reranking.

## Other responses

- `4XX` — Client error <p> This indicates an issue with the request format or frequency. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide. </p>
- `5XX` — Server Error <p> This indicates our servers are experiencing high traffic or having an unexpected issue. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide. </p>

---

[API](https://skmtc.net/voyageai/apis/voyage-api.md) · [All operations](https://skmtc.net/voyageai/apis/voyage-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voyageai/voyage-api/revisions/b5a3e09c43ce/schema)