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

# Rerank

`POST /rerank`

Rank a list of documents according to their relevance to a query primarily and your custom instructions secondarily.  We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. The reranker supports multilinguality.

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

See our [blog post](https://contextual.ai/blog/introducing-instruction-following-reranker/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb). Email [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any feedback or questions.

## 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 and the optional instruction
  - `model` string, required — The version of the reranker to use. Currently, we have: "ctxl-rerank-v2-instruct-multilingual", "ctxl-rerank-v2-instruct-multilingual-mini", "ctxl-rerank-v1-instruct".
  - `top_n` integer — The number of top-ranked results to return
  - `instruction` string — Instructions that the reranker references when ranking documents, after considering relevance. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. For instructions related to recency and timeframe, specify the timeframe (e.g., instead of saying "this year") because the reranker doesn't know the current date. Example: "Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications."
  - `metadata` string[] — Metadata for documents being passed to the reranker. Must be the same length as the documents list. If a document does not have metadata, add an empty string.

## 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/ca7f807eec8b/schema)