# Rerank

> Sort documents by relevance to a query with POST /v1/rerank: models, request, response and pricing.

```text
POST https://api.clonvo.com/v1/rerank
```

Sort documents by how relevant they are to a query, for search and retrieval. The request and response follow OpenRouter's rerank API, and use the same API key, credits, your own provider keys and spending limits as chat completions. Rerank models only serve this endpoint: sending one to chat completions or embeddings returns `400`.

| Model id | Provider | Documents | Limits | Price |
| --- | --- | --- | --- | --- |
| `qwen/qwen3-rerank` | Alibaba Cloud (Qwen) | Text, up to 500 | 4,000 tokens per query or document, 120,000 per request | $0.10 per 1M tokens |

```ts
const res = await fetch("https://api.clonvo.com/v1/rerank", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CLONVO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "qwen/qwen3-rerank",
    query: "What is the capital of France?",
    documents: ["Paris is the capital of France.", "Berlin is the capital of Germany."],
    top_n: 1,
  }),
});
const { results } = await res.json();
console.log(results[0].document.text);
```

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | **Required.** A model id from the table above. |
| `query` | string | **Required.** The text to rank the documents against. |
| `documents` | array | **Required.** The documents, as strings or `{"text": "…"}` objects. Image documents (`{"image": "<URL or data URI>"}`) only work on models that take images. |
| `top_n` | integer | Return only the most relevant `top_n` documents. Defaults to all of them. |
| `provider` | object | **Extension.** `order` and `allow_fallbacks` choose between your own key and credits (see [Fallbacks and routing](https://clonvo.com/docs/fallbacks.md)). |

## Response

```json
{
  "id": "gen-01M6B2XK7Q4R8S1T3V5W7Y9Z2A",
  "model": "qwen/qwen3-rerank",
  "provider": "Alibaba Cloud (Qwen)",
  "results": [
    { "index": 0, "relevance_score": 0.83, "document": { "text": "Paris is the capital of France." } }
  ],
  "usage": { "total_tokens": 56, "cost": 0.0000056, "is_byok": false }
}
```

`results` are sorted by `relevance_score`, highest first; `index` is the document's position in your request, and `document` echoes it. Scores are relative to the other documents in the same request. `usage.total_tokens` is what the provider billed: Alibaba counts the query once per document plus every document. `usage.cost` is what the request cost. The `x-clonvo-generation-id` header holds the generation id.

## Listing rerank models

`GET /v1/models?output_modalities=rerank` lists them, as on OpenRouter; they aren't in the default list, which holds chat models.

## Errors

Models that aren't rerank models return `400` `model_wrong_kind`; image documents on a text-only model return `400` `unsupported_content`, and more documents than the model takes return `400` `too_many_documents`. A query or document over the model's token limit is refused by the provider with `400`, not truncated. Everything else is as for chat (see [Errors](https://clonvo.com/docs/errors.md)).