Rerank API

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, as qwen/qwen3-reranker-0.6b. The reranker doesn’t take Chat Completions requests.

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."
    ]
  }'

{
  "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:

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.

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 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.
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, 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.

API Documentation

Compute API

Inference API

Traces API

Availability

Billing

Disks

evals

factory

Feedback

hosted-evaluations

Images

inference

metrics

Pods

Secrets

slurm-clusters

SSH Keys

teams

API Keys

training

Tunnel

user

Request body

Response

Usage and billing

Errors

OpenRouter compatibility

​Request body

​Response

​Usage and billing

​Errors

​OpenRouter compatibility

Request body

Response

Usage and billing

Errors

OpenRouter compatibility