Skip to main content
Send a query and a list of documents to POST /v1/rerank, and NagaAI returns the documents ordered from most to least relevant, each with a score. A reranker reads the query and each document together, so it judges relevance more precisely than comparing embeddings. The usual setup is a fast search for a few dozen candidates and a rerank of them. Only the top few then go to a chat model. The request and response follow the format OpenRouter, Cohere and Jina use. Choose a model whose operations include rerank in GET /v1/models.

Rank search results

The example ranks three support articles against a question and keeps the best two.
results holds the documents most relevant first. index is the document’s position in the documents you sent, counted from 0, so you can map a result back to your own record. NagaAI bills the request for usage.total_tokens:

Request fields

model, query and documents are required. documents holds from 1 to 1,000 entries, each a string or an object with text. top_n keeps only that many of the best results; without it every document comes back, ranked. Set return_documents to false to get index and relevance_score without the text, which keeps the response small when you already hold the documents. Scores are each model’s own scale. Compare them within one response or one model. Pick a cut-off by testing on your own data, not by reusing a number from another model. NagaAI orders the results itself and cuts them to top_n, so the response has the same shape whichever provider served the model.

Fall back to another model

List up to three fallback models in models, in the order to try them. If no provider of the model you asked for can rank the documents, NagaAI sends the same request to the next model. The model field in the response names the one that answered. Scores of different models are not comparable, so read model before you apply a cut-off. Routing explains when NagaAI moves on and what you pay.
cURL

Billing

Most rerank models charge for the tokens they read, at the model’s input token price in GET /v1/models. The model reads the query beside every document, so the query counts once per document, plus the documents themselves. Long queries over many documents cost more than the same documents with a short query. Cohere’s Rerank 3.5 and Rerank 4 models charge per search instead. Their pricing has an input_text_search row, and usage.search_units in the response says how many searches the request cost. One search is one query over up to 100 documents. A document longer than 500 tokens together with the query is split into chunks of that size, and each chunk counts as a document. So 250 short documents cost three searches, and one query over 100 long documents costs more than one. When the provider reports its count, NagaAI bills that count; otherwise it counts the tokens and searches itself. See Price of a request.

Troubleshooting

400 model_not_found

The model does not exist or has no rerank operation. Check its operations in GET /v1/models.

400 on body.documents

documents is empty or holds more than 1,000 entries. Split a longer list into batches and merge the results by score from one model.

400 on body.top_n

top_n is below 1. Leave it out to get every document back.