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

# Submit a rerank request

`POST /rerank`

Submits a rerank request to the rerank router

## Request body

- object — Rerank request input
  - `documents` union[], required — The list of documents to rerank. Documents may be plain strings, or structured objects with `text` and/or `image` for multimodal models.
    - union — A document to rerank. Either a plain string, or a structured object with optional `text` and/or `image`.
      - string
      - object — A structured document with optional text and/or image content. At least one of `text` or `image` must be provided.
        - `image` string — An image associated with the document, as a remote URL (http/https) or a base64-encoded data URI (data:image/...).
        - `text` string — The document text
  - `model` string, required — The rerank model to use
  - `query` string, required — The search query to rerank documents against
  - `top_n` integer — Number of most relevant documents to return

## Response `200`

Rerank response

- object — Rerank response containing ranked results
  - `id` string — Unique identifier for the rerank response (ORID format)
  - `model` string, required — The model used for reranking
  - `provider` string — The provider that served the rerank request
  - `results` object[], required — List of rerank results sorted by relevance
    - `document` object, required — The document object echoing the original input (text and/or image)
      - `image` string — The image (URL or data URI) from the original document
      - `text` string — The document text
    - `index` integer, required — Index of the document in the original input list
    - `relevance_score` number, double, required — Relevance score of the document to the query
  - `usage` object — Usage statistics
    - `cost` number, double — Cost of the request in credits
    - `search_units` integer — Number of search units consumed (Cohere billing)
    - `total_tokens` integer — Total number of tokens used

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `402` — Payment Required - Insufficient credits or quota to complete request
- `404` — Not Found - Resource does not exist
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error
- `502` — Bad Gateway - Provider/upstream API failure
- `503` — Service Unavailable - Service temporarily unavailable
- `524` — Infrastructure Timeout - Provider request timed out at edge network
- `529` — Provider Overloaded - Provider is temporarily overloaded

---

[API](https://skmtc.net/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.net/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/versions/9d1da2c7d2c3/schema)