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

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
  }'

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"]])

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

{
  "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

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 and in GET /v1/models.

Get Started

Guides

Agents

Reference

Changelog

Chat

Completions

Embeddings

Models

Usage

Example

Request

Response

Billing

See also

​Example

​Request

​Response

​Billing

​See also

Example

Request

Response

Billing

See also