# Rerank API

> POST /api/v1/rerank — score how relevant each document is to a query. Cohere-compatible request and response.


# Rerank API

Score how relevant each document is to a query, then sort them. Use it as a second stage after vector or keyword search: fetch 50–100 candidates, rerank, and keep the top few. The body is compatible with Cohere's Rerank API.

::endpoint{method="POST" path="/api/v1/rerank"}

:::note
Authenticate with an **LLM API key** (`sk-ar-v1-…`) from [/dashboard/keys](https://anyrouter.dev/dashboard/keys), sent as `Authorization: Bearer …`. Management keys (`ak_…`) are not accepted.
:::

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | A rerank model id, e.g. `cohere/rerank-v3.5`. See [Models](#models). |
| `query` | string | yes | The search query. |
| `documents` | (string \| `{text: string}`)[] | yes | Up to 1,000 documents to score. |
| `top_n` | integer (≥ 1) | no | Return only the best `top_n` results. Defaults to all documents. |
| `return_documents` | boolean | no | When `true`, each result includes `document.text`. Defaults to `false`. |
| `max_tokens_per_doc` | integer (≥ 1) | no | Truncate each document to this many tokens before scoring. |
| `session_id` | string | no | Groups related requests in [Request Logs](/features/request-logs#sessions). |

```bash
curl https://anyrouter.dev/api/v1/rerank \
  -H "Authorization: Bearer $ANYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-v3.5",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital and largest city of France.",
      "Berlin is the capital of Germany.",
      "Bananas are rich in potassium."
    ],
    "top_n": 2
  }'
```

## Response

```json
{
  "id": "162b4aa9-d997-4942-896a-ef65644ff544",
  "model": "cohere/rerank-v3.5",
  "results": [
    { "index": 0, "relevance_score": 0.892 },
    { "index": 1, "relevance_score": 0.073 }
  ],
  "usage": {
    "prompt_tokens": 1000,
    "total_tokens": 1000,
    "search_units": 1,
    "cost": 0.002
  }
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Response id. |
| `model` | string | The model id you requested. |
| `results[]` | array | Sorted by `relevance_score`, highest first. |
| `results[].index` | integer | Position of the document in your `documents` array. |
| `results[].relevance_score` | number | Relevance between 0 and 1. Compare scores within one request, not across models. |
| `results[].document` | `{text}` | Present only when `return_documents` is `true`. |
| `usage.prompt_tokens` | integer | Billed tokens (see Pricing). |
| `usage.search_units` | integer | Provider search units, when the provider reports them. |
| `usage.cost` | number | USD charged for this request. |

## Pricing

Rerank models are priced per 1M input tokens, like the rest of the catalog. AnyRouter counts tokens over the query plus every document (about 4 characters per token), because rerank providers do not return token counts. Each provider search unit (one query with up to 100 documents) bills at least 1,000 tokens, so a very small request costs the same as one search.

Requests with your own Cohere key ([BYOK](/features/byok)) are not charged by AnyRouter.

## Models

Rerank models appear under the **Rerank** tab at [anyrouter.dev/models](https://anyrouter.dev/models). Sending a chat or embedding model to this endpoint returns `400 model_not_rerank_compatible`.

## Errors

| Status | Code | When |
|---|---|---|
| 400 | `missing_required_fields` | `model`, `query`, or `documents` is missing. |
| 400 | `invalid_request` | A document is not a string or `{text}`, `top_n` is not a positive integer, or there are more than 1,000 documents. |
| 400 | `model_not_rerank_compatible` | The model is not a rerank model. |
| 404 | `model_unavailable` | No route serves the model for your key. |
| 502 | `upstream_error` | Every provider for the model failed. |