Skip to content

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.