Rerank
A reranker reads your query together with each document and scores how well that document answers it. You get the documents back best first, each with a score. It is slower and more precise than vector search, so it runs second: embeddings find 20 to 50 likely matches, the reranker orders them.
Request
POST https://api.tirtha.ai/v1/rerank with your key. Send model, query (a string) and documents (a list of strings). Two optional fields: top_n returns only the best n, and return_documents: true puts each document’s text in its result. Any other field is refused by name.
curl https://api.tirtha.ai/v1/rerank \
-H "Authorization: Bearer $TIRTHA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tirtha/qwen3-reranker-8b",
"query": "How long does shipping take?",
"documents": [
"Orders ship within three to five business days.",
"You can reset your password from the login page.",
"Refunds go back to the original payment method."
],
"top_n": 2,
"return_documents": true
}'import os, requests
API = "https://api.tirtha.ai/v1"
H = {"Authorization": "Bearer " + os.environ["TIRTHA_API_KEY"]}
def rerank(query, documents, top_n=None):
"""Up to 100 documents, 200,000 characters with the query."""
body = {"model": "tirtha/qwen3-reranker-8b",
"query": query, "documents": documents}
if top_n:
body["top_n"] = top_n
r = requests.post(API + "/rerank", headers=H, json=body, timeout=130)
if r.status_code != 200:
raise RuntimeError(r.status_code, r.json().get("error"))
return r.json()["results"] # best first
docs = ["Orders ship within three to five business days.",
"You can reset your password from the login page.",
"Refunds go back to the original payment method."]
for hit in rerank("How long does shipping take?", docs, top_n=2):
print(round(hit["relevance_score"], 3), docs[hit["index"]])const API = "https://api.tirtha.ai/v1";
const docs = [
"Orders ship within three to five business days.",
"You can reset your password from the login page.",
"Refunds go back to the original payment method.",
];
const r = await fetch(API + "/rerank", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.TIRTHA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "tirtha/qwen3-reranker-8b",
query: "How long does shipping take?",
documents: docs,
top_n: 2,
}),
});
const body = await r.json();
if (!r.ok) throw new Error(r.status + " " + JSON.stringify(body.error));
for (const hit of body.results) { // best first
console.log(hit.relevance_score.toFixed(3), docs[hit.index]);
}Response
results is sorted best first. index is the position of the document in the list you sent in this call. document appears only with return_documents: true.
Example shape; real recorded reply coming. The field names and types are the ones the API returns; the values are examples.
{
"object": "list",
"results": [
{
"index": 0,
"relevance_score": 0.9871,
"document": "Orders ship within three to five business days."
},
{
"index": 2,
"relevance_score": 0.0214,
"document": "Refunds go back to the original payment method."
}
],
"model": "tirtha/qwen3-reranker-8b",
"usage": {
"tokens": 260,
"charged": "0.000016",
"estimated": false
}
}| Field | Type | Meaning |
|---|---|---|
results[].index | integer | Position of the document in your documents list (0 is the first). |
results[].relevance_score | number | How well it answers the query; higher is better. |
results[].document | string | The document text, only with return_documents: true. |
usage.tokens | integer | Input tokens the model counted: the billed amount. |
usage.charged | string | What this call cost, in US dollars, with 6 decimals. |
usage.estimated | boolean | true only if the model did not report a count and our estimate was billed instead. |
Pricing
Per 1M input tokens. The model reads the query again with every document, so the count grows with the number of documents, not only their length. Each model’s price is on the Rerank tab, the one price list for the site.
Before the call runs, a hold for an upper estimate is set aside from your credit; the bill is the counted tokens, and the reply gives the exact amount in usage.charged. Requests that fail are not charged.
Limits
| Limit | Value |
|---|---|
| Documents per call | Up to 100 |
| Characters per call | Up to 200,000 in total, query included |
| Each document | Not empty. The gateway has no separate cap per document; the query and each document together must fit what the model accepts, or the model refuses with 400 request_rejected and nothing is charged. |
top_n | 1 up to the number of documents sent. Leave it out to get them all back. |
| Requests per minute | Set per key. A key with a limit gets 429 quota_exceeded over it, with Retry-After: 60. |
| At capacity | 429 media_busy with Retry-After: 2; nothing is charged. |
| Time | The gateway waits up to 120 seconds for the model. Set your client timeout a little above that. |
Errors
| Status | Code | Message | What to do |
|---|---|---|---|
400 | invalid_input | 'query' and 1-100 non-empty 'documents' strings are required. | Also sent when the query plus documents pass 200,000 characters, or a document is empty. |
400 | invalid_top_n | 'top_n' must be 1-<number of documents>. | Send a whole number no larger than the documents you sent. |
404 | model_not_found | Unknown rerank model. | Use an id from the Rerank tab, with the tirtha/ prefix. |
400 | request_rejected | The request was rejected. Nothing was charged. | The model refused the input, most often a query plus document longer than it accepts. Use shorter chunks. |
402 | insufficient_credits | Not enough prepaid credit for this request (it may need <amount>). | Add credits. A real recorded reply is below. |
Recorded reply, 2026-11-13: HTTP 402 from a key with no credit.
{
"error": {
"message": "Not enough prepaid credit for this request (it may need 0.000038).",
"type": "invalid_request_error",
"code": "insufficient_credits"
}
}Every other error these routes can return (key, terms, rate limit, spend cap, busy, billing) is on Common errors, with what to do for each. Anything refused before the model runs costs nothing.
Best practices
Rerank the top 20 to 50, not everything.
The reranker reads every pair of query and document, so cost and time grow with each document you add. Vector search narrows a large collection fast; give the reranker only its best 20 to 50:
# uses docs, scores and question from the full example on # /docs/embeddings, and rerank() from the Python request example order = sorted(range(len(docs)), key=lambda i: scores[i], reverse=True) candidates = order[:30] hits = rerank(question, [docs[i] for i in candidates], top_n=5) best = [docs[candidates[h["index"]]] for h in hits]Map
indexback to your own ids.indexpoints into the list you sent in this call, not into your database. Keep the candidate list you built, as above, and look each result up in it.Use
top_nwhen you only show a few.If the page shows five results, ask for five. The reply is smaller and already in order.
Compare scores within one call.
A score ranks documents against one query. Do not compare scores across queries or models, and do not read 0.8 as twice as good as 0.4. If you need a cut-off, pick it from a few dozen of your own real queries with known good and bad answers.
Turn records into short text, key fields first.
The reranker reads text. For products, tickets or rows, write each record as a few labelled lines with the fields that decide relevance first, so a long description cannot push them out:
# a product record as one short block of text, the key fields first def as_text(p): return (f"Title: {p['title']}\n" f"Category: {p['category']}\n" f"Price: {p['price']}\n" f"Description: {p['description']}") documents = [as_text(p) for p in products] # products: your own recordsRerank the chunks you embedded, not whole files.
A long document mixes topics and can lose to a short one that answers the question directly.
Keep the query short and the documents clean.
The query is read once per document, so a long query multiplies. Strip markup, boilerplate and empty strings; an empty document refuses the whole call with
invalid_input.
Full example
The complete search flow (embed once, the query with its instruction, normalized vectors, then this reranker on the top candidates) is the full example on the Embeddings page. It runs as pasted.
Checked against the API code on 2026-11-14. Tīrtha is still being built; limits and fields may change, and this page changes with them.