> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank API

> Order documents by their relevance to a query

`POST https://api.pinference.ai/api/v1/rerank` scores each document against a query and returns the documents most relevant first. Prime Inference serves one reranker, [Qwen3 Reranker 0.6B](https://docs.primeintellect.ai/inference/models/qwen3-reranker), as `qwen/qwen3-reranker-0.6b`. The reranker doesn't take Chat Completions requests.

```bash theme={null}
export PRIME_API_KEY="your-api-key"

curl https://api.pinference.ai/api/v1/rerank \
  -H "Authorization: Bearer $PRIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-reranker-0.6b",
    "query": "Which planet is known as the Red Planet?",
    "documents": [
      "Venus is often called Earth'\''s twin because of its similar size.",
      "Mars is often referred to as the Red Planet.",
      "Jupiter has a prominent red spot."
    ]
  }'
```

```json theme={null}
{
  "id": "req_...",
  "model": "qwen/qwen3-reranker-0.6b",
  "results": [
    {"index": 1, "relevance_score": 0.997, "document": {"text": "Mars is often referred to as the Red Planet."}},
    {"index": 0, "relevance_score": 0.025, "document": {"text": "Venus is often called Earth's twin because of its similar size."}},
    {"index": 2, "relevance_score": 0.010, "document": {"text": "Jupiter has a prominent red spot."}}
  ],
  "usage": {"total_tokens": 270}
}
```

The same request in Python:

```python theme={null}
import os
import requests

response = requests.post(
    "https://api.pinference.ai/api/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['PRIME_API_KEY']}"},
    json={
        "model": "qwen/qwen3-reranker-0.6b",
        "query": "Which planet is known as the Red Planet?",
        "documents": [
            "Venus is often called Earth's twin because of its similar size.",
            "Mars is often referred to as the Red Planet.",
            "Jupiter has a prominent red spot.",
        ],
    },
    timeout=120,
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["index"], round(result["relevance_score"], 3), result["document"]["text"])
```

To charge a team, add `-H "X-Prime-Team-ID: your-team-id"` to each request. See [team billing](https://docs.primeintellect.ai/inference/overview.md#team-billing).

## Request body

| Field | Type | Description |
| - | - | - |
| `model` | string | `qwen/qwen3-reranker-0.6b`. |
| `query` | string | The text each document is scored against. |
| `documents` | array | 1 to 1,000 documents. Each is a string or an object with a `text` string. The model reads text only, so a document with an `image` is refused. |
| `top_n` | integer | Optional. The number of results to return, at least 1. A `top_n` above the number of documents returns them all. Without `top_n`, every document is returned. |
| `instruction` | string | Optional. A one-line description of the task, which the model reads with every document. The default is `Given a web search query, retrieve relevant passages that answer the query`. An empty string keeps the prompt's `<Instruct>:` label with nothing after it. |

The model reads each document in its own prompt, with the query, the instruction and the prompt template. One prompt can hold 32,768 tokens, template included. A longer prompt is refused with a 400, and nothing is truncated. Split or shorten long documents before you send them. The whole request body can be at most 16 MiB.

## Response

| Field | Description |
| - | - |
| `id` | The request's ID, the same as the `X-Inference-Id` response header. Share it with support to trace a request. |
| `model` | The model ID from the request. |
| `results` | The most relevant `top_n` documents, or every document without `top_n`, most relevant first. |
| `results[].index` | The document's position in the request's `documents`, counting from 0. |
| `results[].relevance_score` | The model's probability, from 0 to 1, that the document meets the query and the instruction. |
| `results[].document` | The document's text, as `{"text": "..."}`. |
| `usage.total_tokens` | The tokens the model read, summed over every document's prompt. |

Results are sorted by the model's raw score, the logit behind each probability. Documents with equal logits keep their request order. Two documents with very high logits can both score exactly 1.0. The response doesn't include logits, so keep the order of `results` and don't re-sort by `relevance_score`.

## Usage and billing

Reranking is billed on input tokens, `usage.total_tokens`, at \$0.20 per million. There is no output charge. Each document is billed for its own tokens, the query's tokens and about 70 tokens of default instruction and template.

## Errors

Most errors return an `error` object with `message`, `type` and `code`, as the [Chat Completions API](https://docs.primeintellect.ai/api-reference/inference-chat-completions.md) does. A 401, a 404, or a 503 while authentication is unavailable returns a `detail` message instead.

| Status | Cause |
| - | - |
| 400 | The request breaks a rule above. The message names the rule, as in `Invalid rerank request (top_n).` The rules are `query`, `documents`, `too_many_documents`, `image_documents`, `top_n` and `instruction`. A prompt longer than 32,768 tokens returns `Invalid rerank request (input).` |
| 401 | The API key is missing or invalid. |
| 402 | The billed account has insufficient funds. See [troubleshooting](https://docs.primeintellect.ai/inference/troubleshooting.md). |
| 404 | The request didn't name a reranker, or its body isn't JSON. A misspelled model ID, a missing `model` and a non-JSON body all return a `detail` of `Not Found`. This check comes before the API key check, so a wrong model with a bad key returns 404. |
| 413 | The request body is larger than 16 MiB. |
| 429 | The model has no free capacity. Retry after the number of seconds in the `Retry-After` header. |
| 502 or 503 | The model failed to answer. Retry the request. |

## OpenRouter compatibility

Requests and responses use the same fields as [OpenRouter's rerank API](https://openrouter.ai/docs/api/api-reference/rerank/submit-a-rerank-request), which follows Cohere's naming. A client written for that API works with Prime Inference after you change its base URL and API key. The `instruction` field is specific to Prime Inference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.