Rerank

POSThttps://api.oneinfer.ai/v1/ula/rerank

Order documents by how relevant they are to a query, best first: for retrieval-augmented generation (RAG), search and recommendations. The request follows Cohere's rerank format.

Request headers

Authorizationstringrequired

Bearer token for authentication. Format: Bearer <YOUR_TOKEN>. Exchange your API key for a token via the Authentication endpoint.

Content-Typestringrequired

application/json

Request parameters

modelstringrequired

A rerank model, for example Qwen/Qwen3-Reranker-4B. The Rerank type in the model catalog lists them all.

querystringrequired

What the documents are ranked against.

documentsstring[]required

The texts to rank: 1 to 1,000 strings, none empty.

top_ninteger

Return only the best n results. By default every document is returned.

return_documentsboolean

Include each document's text in its result as document.text. Default false.

instructionstring

What counts as relevant, up to 2,000 characters, for example "Find the passage that answers the question". The Qwen3 rerankers use it.

Good to know

Each result's index is the document's position in documents; results come best first.
Scores aren't comparable between models. Nemotron 3.5 Rerank's scores are unbounded, not between 0 and 1, so rely on the order rather than the number.
You pay per input token (the query and the documents), at the model's price per million tokens.

Example request

POST {BASE_URL}/v1/ula/rerank

{
  "model": "Qwen/Qwen3-Reranker-4B",
  "query": "What is the capital of France?",
  "documents": [
    "Bananas are yellow.",
    "Paris is the capital of France.",
    "The Eiffel Tower is in Paris."
  ],
  "top_n": 2,
  "return_documents": true
}

Response

JSON

200 OK

{
  "model": "Qwen/Qwen3-Reranker-4B",
  "results": [
    {
      "index": 1,
      "relevance_score": 0.958,
      "document": {
        "text": "Paris is the capital of France."
      }
    },
    {
      "index": 2,
      "relevance_score": 0.1319,
      "document": {
        "text": "The Eiffel Tower is in Paris."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 255,
    "total_tokens": 255,
    "credits_used": 0.00070125
  }
}

Error status codes

Code	Status	Description
`200`	OK	The reply is ready; usage.credits_used is what was charged.
`400`	Bad Request	The model isn't a rerank model.
`401`	Unauthorized	Missing or invalid Authorization header / Bearer token.
`403`	Forbidden	Your account balance is too low.
`422`	Unprocessable Entity	The request body failed validation, for example an empty or missing field.
`502`	Bad Gateway	The provider serving the model failed. Try again later.
`503`	Service Unavailable	The model is busy or unavailable. Retry after a short wait.

Response

202 - application/json