Rerank
POST /v1/rerank scores documents against a query and returns them all, most relevant first. This helps search and RAG
pipelines select the best matches. It accepts the request format used by Cohere, Jina and RAG libraries, so existing
clients can use Keln by changing the base URL. API keys, rate limits and billing work the same as for chat
completions.
import os, requests
resp = requests.post(
"https://api.keln.ai/v1/rerank",
headers={"Authorization": f"Bearer {os.environ['KELN_API_KEY']}"},
json={
"model": "qwen/qwen3-reranker-8b",
"query": "What is the capital of France?",
"documents": ["Berlin is the capital of Germany.", "Paris is the capital of France."],
"top_n": 1,
},
)
print(resp.json()["results"])
const resp = await fetch("https://api.keln.ai/v1/rerank", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.KELN_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
model: "qwen/qwen3-reranker-8b",
query: "What is the capital of France?",
documents: ["Berlin is the capital of Germany.", "Paris is the capital of France."],
top_n: 1,
}),
});
console.log((await resp.json()).results);
curl https://api.keln.ai/v1/rerank \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen/qwen3-reranker-8b",
"query": "What is the capital of France?",
"documents": ["Berlin is the capital of Germany.", "Paris is the capital of France."],
"top_n": 1
}'
The answer:
{
"object": "rerank",
"model": "qwen/qwen3-reranker-8b",
"results": [{"index": 1, "relevance_score": 0.9774}],
"usage": {"prompt_tokens": 170, "total_tokens": 170, "cost": 0.000010625}
}
Request
| Field | Contract |
|---|---|
model |
A rerank model id from GET /v1/models: rows where output_modalities is ["rerank"]. Keln returns 400 wrong_endpoint for a chat model on this endpoint, and for a rerank model on chat completions. |
query |
Required. A non-empty string. |
documents |
Required. Up to 1,000 non-empty strings, or {"text": "…"} objects with nothing else in them. |
top_n |
Optional. Return only the best top_n. More than the number of documents returns them all. |
return_documents |
Optional. true adds each document's text to its result. Default false. |
instruction |
Optional. A task instruction, up to 2,048 characters, telling the model what "relevant" means for your task. A model that takes no instruction returns 400 rerank_shape_not_supported. |
Other fields, such as rank_fields or max_chunks_per_doc, return 400 invalid_request.
What you get
results contains each document's index from the request and its relevance_score, sorted from most to least
relevant. Ties keep the original document order. Keln scores every document regardless of top_n, so top_n changes the
returned results, not the bill.
Billing
Keln bills rerank models for input tokens only. The model scores each document with the query and its own prompt
template, so the billed token count includes more than your text alone. usage.prompt_tokens shows the count, and
usage.cost shows the exact charge based on the model's price in GET /v1/models.
Errors
| Code | Meaning |
|---|---|
rerank_shape_not_supported |
The model can't take this request: more documents than it accepts (its page on keln.ai/models lists the limit), or an instruction it doesn't apply. |
wrong_endpoint |
A chat model on this endpoint, or a rerank model on chat completions. |
invalid_request |
An empty query or document, more than 1,000 documents, or a field Keln doesn't take. |
model_not_found, rate and balance errors |
As on every Keln endpoint (errors & limits). |
Keys, budgets and zero data retention work the same as on chat completions.