> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/inference-api/rerank.md).

# Rerank

Score documents against a query and return them ranked by relevance.

Score a set of documents against a query and return them ordered by relevance. For how this fits into a retrieval pipeline, see [Reranking](/products/serverless-inference/reranking.md).

## HTTP Request

`POST` `{API_URL}/rerank`

where `API_URL = https://inference.nebulablock.com/v1`.

## Body Parameters

#### model `string` *required*

The reranking model to use, for example `BAAI/bge-reranker-v2-m3`.

#### query `string` *required*

The search query to score documents against.

#### documents `list` *required*

The list of documents to rerank.

#### top\_n `integer`

Return only the top N results. Defaults to returning every document.

#### return\_documents `boolean`

Include the document text in each result alongside its score.

#### rank\_fields `list`

For structured documents, the fields to rank on.

#### max\_tokens\_per\_doc `integer`

Truncate each document to this many tokens before scoring.

## Response Attributes

#### id `string`

Identifier for the reranking request.

#### results `list`

The reranked documents, ordered by descending relevance. Each entry contains:

* **index** `integer`: Position of the document in the `documents` array you sent.
* **relevance\_score** `float`: Relevance score, higher is more relevant.
* **document** `object`: `{"text": "..."}`, present when `return_documents` is `true`.

#### meta `dict`

Usage details for the request: **billed\_units** (`search_units`, `total_tokens`) and **tokens** (`input_tokens`, `output_tokens`).

## Example

#### Request

```bash
curl -X POST "https://inference.nebulablock.com/v1/rerank" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $NEBULA_API_KEY" \
    --data-raw '{
        "model": "BAAI/bge-reranker-v2-m3",
        "query": "How do I rent a GPU by the hour?",
        "documents": [
            "Object Storage is an S3-compatible service for datasets and checkpoints.",
            "GPU instances are billed hourly and can be deployed in minutes from the console.",
            "Tier 3 requires a $10 deposit."
        ],
        "top_n": 2
    }'
```

#### Response

```json
{
  "id": "rerank-...",
  "results": [
    { "index": 1, "relevance_score": 0.98 },
    { "index": 2, "relevance_score": 0.41 }
  ]
}
```

## See also

* [Reranking](/products/serverless-inference/reranking.md)
* [Embeddings](/api-reference/inference-api/embeddings.md)
* [Model Catalog](/products/serverless-inference/model-catalog.md)