> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank

> Rank retrieved documents by relevance to a query before passing them to a model.

`POST /v3/rerank` scores a list of documents against a query and returns the most relevant first. Use it after retrieving candidate passages, then pass the highest-ranked results into your model's context.

Authenticate with a project API key. Reranking requires a paid plan.

## Rerank documents

Send a model, a query, and up to 1,000 document strings. Set `top_n` to limit the results and `return_documents` to include their text.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.opper.ai/v3/rerank \
    -H "Authorization: Bearer $OPPER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "bge-reranker-v2-m3",
      "query": "How do I reset my password?",
      "documents": [
        "Billing and invoices",
        "Use the forgot-password link to reset your password",
        "Release notes"
      ],
      "top_n": 1,
      "return_documents": true
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.opper.ai/v3/rerank",
      headers={"Authorization": f"Bearer {os.environ['OPPER_API_KEY']}"},
      json={
          "model": "bge-reranker-v2-m3",
          "query": "How do I reset my password?",
          "documents": [
              "Billing and invoices",
              "Use the forgot-password link to reset your password",
              "Release notes",
          ],
          "top_n": 1,
          "return_documents": True,
      },
      timeout=65,
  )
  response.raise_for_status()
  for result in response.json()["results"]:
      print(result["index"], result["relevance_score"], result["document"]["text"])
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.opper.ai/v3/rerank", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPPER_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "bge-reranker-v2-m3",
      query: "How do I reset my password?",
      documents: [
        "Billing and invoices",
        "Use the forgot-password link to reset your password",
        "Release notes",
      ],
      top_n: 1,
      return_documents: true,
    }),
  });
  if (!response.ok) throw new Error(await response.text());
  const { results } = await response.json();
  for (const result of results) {
    console.log(result.index, result.relevance_score, result.document.text);
  }
  ```
</CodeGroup>

The response contains `results`, a generation `id`, the `model` endpoint that served the request, and `usage`. Each result's `index` points to its original position in your `documents` array, even after sorting. For this example, the password-reset passage at index `1` ranks first.

| Field              | Behavior                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`            | Required. A rerank model name or a fully qualified endpoint ID.                                                                                  |
| `query`            | Required. A nonblank search query.                                                                                                               |
| `documents`        | Required. An array of 1–1,000 strings. Providers may impose additional document-length limits.                                                   |
| `top_n`            | Optional integer, at least 1. Omit to return all documents.                                                                                      |
| `return_documents` | Defaults to `false`. Set to `true` to include `results[].document.text`; otherwise use `results[].index` to retrieve the original text yourself. |
| `top_k`            | Compatibility alias for `top_n`. Zero means unspecified. If both fields have positive values, they must match; conflicting values return `400`.  |

## Choose a model

List available rerank models with `GET /v3/models?type=rerank`:

```bash theme={null}
curl "https://api.opper.ai/v3/models?type=rerank" \
  -H "Authorization: Bearer $OPPER_API_KEY"
```

A bare name, such as `bge-reranker-v2-m3` or `rerank-v3.5`, selects from that model's pooled endpoints. If an endpoint fails and another eligible endpoint exists, Opper tries the next one. A fully qualified ID, such as `berget/bge-reranker-v2-m3` or `aws/cohere/rerank-v3.5`, pins one endpoint and does not fall back.

The project's model access rules and provider entitlements apply to every candidate, including fallback endpoints. The response's `model` identifies the endpoint that answered.

## Usage and cost

`usage.total_tokens` contains the provider's reported token count. Rerank tokens are recorded as input tokens; no output text tokens are generated. Providers that do not report tokens return `0`, which does not mean the call is free.

Billing follows the selected endpoint's catalog price: per input token for Berget BGE, or per call for Bedrock Cohere. `usage.cost` and the `X-Generation-Cost` response header report the cost in USD. A successful request is billed for the endpoint that served it. Limiting the returned results with `top_n` does not limit the candidate documents sent for scoring.

## Errors

| Status | Meaning                                                                                   |
| ------ | ----------------------------------------------------------------------------------------- |
| `400`  | Invalid input, an unknown or wrong-type model, or conflicting `top_n` and `top_k` values. |
| `401`  | Missing or invalid project API key.                                                       |
| `402`  | Reranking is unavailable on the free plan, or billing access is blocked.                  |
| `403`  | Model access rules or a required provider agreement prevent the request.                  |
| `429`  | The upstream provider rate-limited the request and no fallback succeeded.                 |
| `502`  | An upstream service failure prevented completion.                                         |
| `504`  | The request timed out.                                                                    |

Use the rerank URL directly: `https://api.opper.ai/v3/rerank`. The `/v3/compat` base URL used for chat completions does not expose a rerank route.

See the [API reference](/v3-api-reference/rerank/rerank-documents) for the complete request and response schema.