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

# Create a rerank request

`POST /rerank`

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

---

[API](https://skmtc.net/together/apis/together-apis.md) · [All operations](https://skmtc.net/together/apis/together-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/together/together-apis/revisions/468edbdc879c/schema)