---
title: "Rerank API (v2)"
method: POST
path: "/v2/rerank"
---

# Rerank API (v2)

`POST /v2/rerank`

This endpoint takes in a query and a list of texts and produces an ordered array with each text assigned a relevance score.

## Headers

- `X-Client-Name` string

## Request body

- object
  - `model` string, required — The identifier of the model to use, eg `rerank-v3.5`.
  - `query` string, required — The search query
  - `documents` string[], required — A list of texts that will be compared to the `query`. For optimal performance we recommend against sending more than 1,000 documents in a single request. **Note**: long documents will automatically be truncated to the value of `max_tokens_per_doc`. **Note**: structured data should be formatted as YAML strings for best performance.
  - `top_n` integer — Limits the number of returned rerank results to the specified value. If not passed, all the rerank results will be returned.
  - `max_tokens_per_doc` integer — Defaults to `4096`. Long documents will be automatically truncated to the specified number of tokens.
  - `priority` integer — Controls how early the request is handled. Lower numbers indicate higher priority (default: 0, the highest). When the system is under load, higher-priority requests are processed first and are the least likely to be dropped.

## Response `200`

OK

- object
  - `id` string
  - `results` object[], required — An ordered list of ranked documents
    - `index` integer, required — Corresponds to the index in the original list of documents to which the ranked document belongs. (i.e. if the first value in the `results` object has an `index` value of 3, it means in the list of documents passed in, the document at `index=3` had the highest relevance)
    - `relevance_score` number, float, required — Relevance scores are normalized to be in the range `[0, 1]`. Scores close to `1` indicate a high relevance to the query, and scores closer to `0` indicate low relevance. It is not accurate to assume a score of 0.9 means the document is 2x more relevant than a document with a score of 0.45
  - `meta` ApiMeta
    - `api_version` object
      - `version` string, required
      - `is_deprecated` boolean
      - `is_experimental` boolean
    - `billed_units` object
      - `images` number — The number of billed images.
      - `input_tokens` number — The number of billed input tokens.
      - `image_tokens` number — The number of billed image tokens.
      - `output_tokens` number — The number of billed output tokens.
      - `search_units` number — The number of billed search units.
      - `classifications` number — The number of billed classifications units.
    - `tokens` object
      - `input_tokens` number — The number of tokens used as input to the model.
      - `output_tokens` number — The number of tokens produced by the model.
    - `cached_tokens` number — The number of prompt tokens that hit the inference cache.
    - `warnings` string[]

## Other responses

- `400` — This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields
- `401` — This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions
- `403` — This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions
- `404` — This error is returned when a resource is not found. This could be because: - The endpoint does not exist - The resource does not exist eg model id, dataset id
- `422` — This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields
- `429` — Too many requests
- `498` — This error is returned when a request or response contains a deny-listed token.
- `499` — This error is returned when a request is cancelled by the user.
- `500` — This error is returned when an uncategorised internal server error occurs.
- `501` — This error is returned when the requested feature is not implemented.
- `503` — This error is returned when the service is unavailable. This could be due to: - Too many users trying to access the service at the same time
- `504` — This error is returned when a request to the server times out. This could be due to: - An internal services taking too long to respond

---

[API](https://skmtc.net/cohere-ai/apis/api-reference.md) · [All operations](https://skmtc.net/cohere-ai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cohere-ai/api-reference/versions/dbed69eda210/schema)