API
Rerank
POST /v1/rerank — order documents by relevance to a query (Cohere-style rerank). Shares the wallet, API keys and rate limits with chat.Rerank documents#
Only models of type Rerank in the pricing table can be used. Results come back best first.
curl https://<host>/v1/rerank \
-H "Authorization: Bearer sk-runtide-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3-Reranker-0.6B",
"query": "Thủ đô của Việt Nam là gì?",
"documents": [
"Hà Nội là thủ đô của Việt Nam.",
"Phở là món ăn nổi tiếng.",
"Thành phố Hồ Chí Minh là trung tâm kinh tế."
],
"top_n": 2
}'{
"id": "rr-123",
"results": [
{ "index": 0, "relevance_score": 0.98 },
{ "index": 2, "relevance_score": 0.21 }
],
"model": "Qwen/Qwen3-Reranker-0.6B",
"usage": { "total_tokens": 84 }
}Parameters#
model- Rule
- Required. A rerank model.
query- Rule
- Required. Non-empty text.
documents- Rule
- Required. 1 to 1,000 items; each a string or an object with a <code>text</code> string.
top_n- Rule
- Optional positive integer: return only the best N results.
return_documents- Rule
- Optional boolean: include the document in each result.
Billing#
- Billed per input token (USD / 1M tokens): the query and every document.
- Billed tokens = the provider’s reported input tokens (also returned in
usage.total_tokens); if it reports none, the pre-call estimate. - The hold before the call = estimated tokens (tokenizer +10% safety margin) × input price. Not enough balance →
402 insufficient_balance. - Provider errors are not billed. General details: Billing.
Common errors#
HTTP/1.1 400 Bad Request
{"error": {"message": "The model `gpt-4o-mini` is a chat model; use /v1/chat/completions instead.",
"type": "invalid_request_error", "code": "model_type_mismatch"}}400 model_type_mismatch- Cause
- The model is not a rerank model. The message names the correct endpoint.
400 invalid_request- Cause
- query empty, documents empty / more than 1,000 / wrong type, top_n not a positive integer.
404 model_not_found- Cause
- Unknown model name, or the model is disabled.
402 insufficient_balance- Cause
- Not enough balance for the hold — top up or send fewer documents.
All error codes: Error codes.