Reorder a set of documents by relevance to a query using rerank models.
The rerank endpoint scores a list of documents against a query and returns them ordered by relevance. Use it as the second stage of a retrieval pipeline — pull candidates with embeddings or keyword search, then rerank to surface the best matches.
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | A rerank model slug — filter the catalog with ?modality=rerank |
query | string | Yes | The search query to score documents against |
documents | array | Yes | Documents to rank (min 1). Each item is a string, or an object with a text field |
top_n | integer | No | Return only the top N results (default: all, ordered) |
Each result carries the original index into your documents array and a relevance_score, sorted highest-first:
Rerank is billed per search unit (usage.search_units, falling back to total_tokens). Note that some providers do not expose a rerank price in the model feed, in which case the catalog shows "—" rather than "Free" — see the pricing reference.