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

# Rerank

`POST /rerank`

Rank a list of documents according to their relevance to a query and your custom instructions about how to prioritize retrievals. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well.

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. 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 just have "ctxl-rerank-en-v1-instruct".
  - `top_n` integer — The number of top-ranked results to return
  - `instruction` string — Instructions that the reranker references when ranking retrievals. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. Note that we do not guarantee that the reranker will follow these instructions exactly. Examples: "Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications." and "Emphasize forecasts from top-tier investment banks. Recent analysis should take precedence. Disregard aggregator sites and favor detailed research notes over news summaries."
  - `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/194878b194cd/schema)