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

# Rerank

> Order documents by relevance to a query with POST /v1/rerank, to put the best search results first before they reach a model.

Send a query and a list of documents to `POST /v1/rerank`, and NagaAI returns the documents ordered from most to least relevant, each with a score. A reranker reads the query and each document together, so it judges relevance more precisely than comparing [embeddings](https://docs.naga.ac/guides/embeddings.md). The usual setup is a fast search for a few dozen candidates and a rerank of them. Only the top few then go to a chat model. The request and response follow the format OpenRouter, Cohere and Jina use. Choose a model whose `operations` include `rerank` in [`GET /v1/models`](https://docs.naga.ac/get-started/models).

## Rank search results

The example ranks three support articles against a question and keeps the best two.

```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
import json
import os
import urllib.request

body = {
    "model": "qwen/qwen3-reranker-8b",
    "query": "How do I rotate an API key?",
    "documents": [
        "Create a new key, switch your clients to it, then revoke the old one.",
        "The balance is shown in US dollars.",
        "Keys can be limited to a monthly budget.",
    ],
    "top_n": 2,
}
request = urllib.request.Request(
    "https://api.naga.ac/v1/rerank",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NAGA_API_KEY']}",
        "Content-Type": "application/json",
        "User-Agent": "rerank-example/1.0",
    },
)
with urllib.request.urlopen(request) as response:
    results = json.load(response)["results"]

for result in results:
    print(f"{result['relevance_score']:.3f}  {result['document']['text']}")
```

```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
const response = await fetch("https://api.naga.ac/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NAGA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen/qwen3-reranker-8b",
    query: "How do I rotate an API key?",
    documents: [
      "Create a new key, switch your clients to it, then revoke the old one.",
      "The balance is shown in US dollars.",
      "Keys can be limited to a monthly budget.",
    ],
    top_n: 2,
  }),
});
if (!response.ok) throw new Error(await response.text());

const { results } = await response.json();
for (const result of results) {
  console.log(result.relevance_score.toFixed(3), result.document.text);
}
```

```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
curl https://api.naga.ac/v1/rerank \
  -H "Authorization: Bearer $NAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-reranker-8b",
    "query": "How do I rotate an API key?",
    "documents": [
      "Create a new key, switch your clients to it, then revoke the old one.",
      "The balance is shown in US dollars.",
      "Keys can be limited to a monthly budget."
    ],
    "top_n": 2
  }'
```

`results` holds the documents most relevant first. `index` is the document's position in the `documents` you sent, counted from 0, so you can map a result back to your own record. NagaAI bills the request for `usage.total_tokens`:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
{
  "id": "rrk-4tKq7Zc1Nb9Wx2Ry8Vd3Ms6Ph0Q",
  "model": "qwen/qwen3-reranker-8b",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9812,
      "document": {"text": "Create a new key, switch your clients to it, then revoke the old one."}
    },
    {
      "index": 2,
      "relevance_score": 0.1436,
      "document": {"text": "Keys can be limited to a monthly budget."}
    }
  ],
  "usage": {"total_tokens": 61}
}
```

## Request fields

`model`, `query` and `documents` are required. `documents` holds from 1 to 1,000 entries, each a string or an object with `text`. `top_n` keeps only that many of the best results; without it every document comes back, ranked. Set `return_documents` to `false` to get `index` and `relevance_score` without the text, which keeps the response small when you already hold the documents.

Scores are each model's own scale. Compare them within one response or one model. Pick a cut-off by testing on your own data, not by reusing a number from another model.

NagaAI orders the results itself and cuts them to `top_n`, so the response has the same shape whichever provider served the model.

## Fall back to another model

List up to three fallback models in `models`, in the order to try them. If no provider of the model you asked for can rank the documents, NagaAI sends the same request to the next model. The `model` field in the response names the one that answered. Scores of different models are not comparable, so read `model` before you apply a cut-off. [Routing](https://docs.naga.ac/build/routing.md#fallback-models) explains when NagaAI moves on and what you pay.

```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
curl https://api.naga.ac/v1/rerank \
  -H "Authorization: Bearer $NAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-reranker-8b",
    "models": ["qwen/qwen3-reranker-0.6b"],
    "query": "How do I rotate an API key?",
    "documents": ["Create a new key, then revoke the old one.", "The balance is shown in US dollars."]
  }'
```

## Billing

Most rerank models charge for the tokens they read, at the model's input token price in `GET /v1/models`. The model reads the query beside every document, so the query counts once per document, plus the documents themselves. Long queries over many documents cost more than the same documents with a short query.

Cohere's Rerank 3.5 and Rerank 4 models charge per search instead. Their `pricing` has an `input_text_search` row, and `usage.search_units` in the response says how many searches the request cost. One search is one query over up to 100 documents. A document longer than 500 tokens together with the query is split into chunks of that size, and each chunk counts as a document. So 250 short documents cost three searches, and one query over 100 long documents costs more than one.

When the provider reports its count, NagaAI bills that count; otherwise it counts the tokens and searches itself. See [Price of a request](https://docs.naga.ac/build/billing.md#price-of-a-request).

## Troubleshooting

### 400 `model_not_found`

The model does not exist or has no `rerank` operation. Check its `operations` in `GET /v1/models`.

### 400 on `body.documents`

`documents` is empty or holds more than 1,000 entries. Split a longer list into batches and merge the results by score from one model.

### 400 on `body.top_n`

`top_n` is below 1. Leave it out to get every document back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.