---
title: "Create a rerank request"
method: POST
path: "/v1/rerank"
tags: ["Rerank"]
---

# Create a rerank request

`POST /v1/rerank`

## Request

- Base URL: `https://api.together.ai`
- URL: `https://api.together.ai/v1/rerank`
- Auth: HTTP bearer

Rerank a list of documents by relevance to a query. Returns a relevance score and ordering index for each document.

## Request body

- RerankRequest
  - `model` union, required: The model to be used for the rerank request.<br> <br> [See all of Together AI's rerank models](https://docs.together.ai/docs/serverless-models#rerank-models)
    - 'Salesforce/Llama-Rank-v1'
    - string
  - `query` string, required: The search query to be used for ranking.
  - `documents` union, required: List of documents, which can be either strings or objects.
    - object[]
    - string[]
  - `top_n` integer: The number of top results to return.
  - `return_documents` boolean: Whether to return supplied documents with the response.
  - `rank_fields` string[]: List of keys in the JSON Object document to rank by. Defaults to use all supplied keys for ranking.

## Response `200`

200

- RerankResponse
  - `object` 'rerank', required: The object type, which is always `rerank`.
  - `id` string: Request ID
  - `model` string, required: The model to be used for the rerank request.
  - `results` object[], required
    - `index` integer, required
    - `relevance_score` number, required
    - `document` object, required
      - `text` string, nullable
  - `usage` UsageData, nullable
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `400`: BadRequest
- `401`: Unauthorized
- `404`: NotFound
- `429`: RateLimit
- `503`: Overloaded
- `504`: Timeout

## Changes

- **2026-10-22** `bb5257b3173a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/together/apis/together-apis/changes/v1/rerank/post.md)

---

[API](https://skmtc.dev/together/apis/together-apis.md) - [All operations](https://skmtc.dev/together/apis/together-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/together/apis/together-apis/revisions/93438ddac711?raw)