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

# Reranking

> Rank documents against a query on /v1/rerank, billed on input tokens.

Use `POST /v1/rerank` to order search results by relevance before passing the best
documents to a language model. Send a query and document strings; the response
returns scores and the original document indices, highest score first.

## Rerank documents

```bash theme={null}
curl https://api.impossibl.com/v1/rerank \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen/qwen3-reranker-8b",
    "query": "Which document describes machine learning?",
    "documents": [
      "The weather is sunny today.",
      "Machine learning finds patterns in data."
    ],
    "top_n": 1
  }'
```

The response has this shape; scores and token counts depend on your input:

```json theme={null}
{
  "object": "list",
  "model": "qwen/qwen3-reranker-8b",
  "data": [
    { "index": 1, "relevance_score": 0.98, "document": "Machine learning finds patterns in data." }
  ],
  "usage": { "prompt_tokens": 80, "total_tokens": 80 }
}
```

`index` refers to the document's position in your request, starting at zero.
`return_documents: false` omits the document text. `top_n` limits the returned
results; when omitted, all documents are returned. An optional `task` string
describes the ranking task to the model.

## Models and billing

Discover supported models with `GET /v1/models`: rerankers have
`output_modality: "rerank"` and `endpoints: ["/v1/rerank"]`. Qwen3 Reranker 8B is
served by Fireworks at \$0.20 per million input tokens. The provider's reported
`usage.prompt_tokens` determines the charge, including the query/document pairs
it evaluates. There are no generated output tokens. Results and charges appear
in the same [request log](/docs/request-logs) and usage ledger as other API calls.

## Limits

Send 1–1,000 nonempty document strings and a nonempty query. The combined input
is capped at 1,200,000 characters, counting the query and optional task once for
each document. Each query/document pair must also fit the model's context window.
`top_n` must be an integer between 1 and the number of documents.

Reranking is non-streaming and uses the gateway's provider credentials. Requests
require an API key and sufficient credits. Sending this model to a chat or
embedding endpoint returns `400` with the correct `/v1/rerank` destination.