Skip navigation
Contents

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.

Rerank three documents
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
  }'
Response
{
  "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#

400 model_type_mismatch
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.