---
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
  - `session_id` string — A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.
  - `top_n` integer — Number of most relevant documents to return
  - `trace` TraceConfig — Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.
    - `generation_name` string
    - `parent_span_id` string
    - `span_name` string
    - `trace_id` string
    - `trace_name` string
  - `user` string — A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.

## 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
- `403` — Forbidden - Authentication successful but insufficient permissions
- `404` — Not Found - Resource does not exist
- `413` — Payload Too Large - Request payload exceeds size limits
- `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

## Changes

- **2026-09-24** `2ebaa86f752c` — 1 info
  - added the new optional request property `provider/allOf[#/components/schemas/ProviderPreferences]/options`
- **2026-09-17** `3066544509b5` — 3 info
  - added the new `Unbiased` enum value to the request property `provider/allOf[#/components/schemas/ProviderPreferences]/ignore/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `Unbiased` enum value to the request property `provider/allOf[#/components/schemas/ProviderPreferences]/only/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `Unbiased` enum value to the request property `provider/allOf[#/components/schemas/ProviderPreferences]/order/items/anyOf[#/components/schemas/ProviderName]/`
- **2026-09-17** `2de027b6dfcd` — 3 info
  - added the new `TypeSafe` enum value to the request property `provider/allOf[#/components/schemas/ProviderPreferences]/ignore/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `TypeSafe` enum value to the request property `provider/allOf[#/components/schemas/ProviderPreferences]/only/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `TypeSafe` enum value to the request property `provider/allOf[#/components/schemas/ProviderPreferences]/order/items/anyOf[#/components/schemas/ProviderName]/`
- **2026-09-16** `98e12733cd62` — 1 info
  - added the new optional request property `session_id`
- **2026-09-15** `81e9c582ae1c` — 1 info
  - added the new optional request property `trace`

[Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/rerank/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/5e8add02feed?raw)