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

# Rerank

> Score documents against a query via `POST /v1/rerank`.

A reranker scores each document against a query, so you can put the most relevant ones first. Use it after retrieval to sharpen what you pass to a model, or to choose between candidates a model has generated. One call scores every document, and there is no prompt to tune.

The serverless reranker is `Qwen3-Reranker-8B`. The body is the Cohere-style rerank shape. The OpenAI SDKs have no rerank method, so call the endpoint directly.

## Example

```bash cURL theme={null}
curl https://api.flex.ai/v1/rerank \
  -H "Authorization: Bearer $FLEXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-Reranker-8B",
    "query": "What is the capital of France?",
    "documents": ["Paris is the capital of France.", "Berlin is the capital of Germany."],
    "top_n": 2
  }'
```

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

documents = ["Paris is the capital of France.", "Berlin is the capital of Germany."]

resp = requests.post(
    "https://api.flex.ai/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['FLEXAI_API_KEY']}"},
    json={
        "model": "Qwen3-Reranker-8B",
        "query": "What is the capital of France?",
        "documents": documents,
        "top_n": 2,
    },
)
resp.raise_for_status()
results = resp.json()["results"]

for r in results:
    print(r["index"], round(r["relevance_score"], 4), documents[r["index"]])
```

```typescript TypeScript theme={null}
const resp = await fetch("https://api.flex.ai/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLEXAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "Qwen3-Reranker-8B",
    query: "What is the capital of France?",
    documents: ["Paris is the capital of France.", "Berlin is the capital of Germany."],
    top_n: 2,
  }),
});

const { results } = await resp.json();
for (const r of results) console.log(r.index, r.relevance_score.toFixed(4));
```

## Request

| Field | Required | Notes |
| - | - | - |
| `model` | Yes | A rerank model, such as `Qwen3-Reranker-8B`. |
| `query` | Yes | The text the documents are scored against. |
| `documents` | Yes | A list of strings to score. |
| `top_n` | No | Return only the `n` highest-scoring documents. Leave it out to score them all. |
| `instruction` | No | A short task description the model uses when scoring, for example `"Given a web search query, retrieve relevant passages"`. |

`return_documents` and `rank_fields` are accepted and have no effect.

## Response

```json theme={null}
{
  "id": "...",
  "results": [
    { "index": 0, "relevance_score": 0.9995, "document": { "text": "Paris is the capital of France." } },
    { "index": 1, "relevance_score": 0.0002, "document": { "text": "Berlin is the capital of Germany." } }
  ],
  "meta": { "billed_units": { "total_tokens": 31 }, "tokens": { "input_tokens": 31 } },
  "usage": { "prompt_tokens": 31, "completion_tokens": 0, "total_tokens": 31 }
}
```

`index` points into your `documents` list, so `documents[r["index"]]` is the scored text. Each result also echoes the document's text in `document.text`. A higher `relevance_score` means a closer match to the query. Sort by `relevance_score` when order matters to you.

To pick the single best document, continuing the example above:

```python Python theme={null}
best = documents[max(results, key=lambda r: r["relevance_score"])["index"]]
```

## Billing

A rerank call bills on input tokens only: the query plus every document. It generates nothing, so output is free. `usage.prompt_tokens` is the count you are billed for. Rates are on [the model page](https://flex.ai/models/qwen3-reranker-8b) and in `GET /v1/models`.

## See also

* [Embeddings](https://docs.flex.ai/inference-api/guides/embeddings.md) — retrieve candidates first, then rerank them.
* [Model discovery](https://docs.flex.ai/inference-api/guides/model-discovery.md) — rerank models have `category: "rerank"`.


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