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

# Rerank

`POST /rerank`

Rank a list of documents according to their relevance to a query.

The total request cannot exceed 400,000 tokens. The combined length of any document, instruction and the query must not exceed 4,000 tokens.

## Request body

- RerankRequestV1 — Rerank input request object.
  - `query` string, required — The string against which documents will be ranked for relevance
  - `documents` string[], required — The texts to be reranked according to their relevance to the query
  - `model` string, required — The version of the reranker to use. Currently, we just have "v1".
  - `top_n` integer — The number of top-ranked results to return
  - `instruction` string — The instruction to be used for the reranker
  - `metadata` string[] — Metadata for documents being passed to the reranker. Must be the same length as the documents list.

## Response `200`

Successful Response

- RerankResponseV1 — Rerank output response.
  - `results` RerankedResultItem[], required — The ranked list of documents containing the index of the document and the relevance score, sorted by relevance score.
    - `index` integer, required — Index of the document in the input list, starting with 0
    - `relevance_score` number, required — Relevance scores assess how likely a document is to have information that is helpful to answer the query. Our model outputs the scores in a wide range, and we normalize scores to a 0-1 scale and truncate the response to 8 decimal places. Our reranker is designed for RAG, so its purpose is to check whether a document has information that is helpful to answer the query. A reranker that is designed for direct Q&A (Question & Answer) would behave differently.

## Other responses

- `422` — Validation Error

## Changes

- **2025-02-26** `5298551c424b` — 1 breaking, 3 info
  - the `documents` request property's minItems was increased to `1`
  - added the new optional request property `instruction`
  - added the new optional request property `metadata`
  - the `query` request property's minLength was decreased from `1` to `0`
- **2025-02-08** `d79ccb778953` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/contextualai/apis/endpoints/changes/rerank/post.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) · [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/contextualai/endpoints/revisions/5298551c424b/schema)