# Rerank results

For guidance and examples, see [Rerank results](/guides/index-data-search-rerank-results).

`POST /rerank`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://api.pinecone.io/rerank \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "bge-reranker-v2-m3",
  "query": "What is the capital of France?",
  "top_n": 5,
  "return_documents": true,
  "rank_fields": [
    "<string>"
  ],
  "documents": [
    {
      "id": "1",
      "text": "Paris is the capital of France.",
      "title": "France",
      "url": "https://example.com"
    }
  ],
  "parameters": {
    "truncate": "END"
  }
}'
```

```json title="200"
{
  "model": "bge-reranker-v2-m3",
  "data": [
    {
      "index": 123,
      "score": 0.5,
      "document": {
        "id": "1",
        "text": "Paris is the capital of France.",
        "title": "France",
        "url": "https://example.com"
      }
    }
  ],
  "usage": {
    "rerank_units": 1
  }
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Headers

- `X-Pinecone-Api-Version` (header, string, required) — Required date-based version header

## Body

- `model` (body, string, required) — The [model](/guides/index-data-search-rerank-results#reranking-models) to use for reranking.
- `query` (body, string, required) — The query to rerank documents against.
- `top_n` (body, integer) — The number of results to return sorted by relevance. Defaults to the number of inputs.
- `return_documents` (body, boolean) — Whether to return the documents in the response.
- `rank_fields` (body, string\[]) — The field(s) to consider for reranking. If not provided, the default is `["text"]`. The number of fields supported is [model-specific](/guides/index-data-search-rerank-results#reranking-models).
- `documents` (body, object\[], required) — The documents to rerank.
- `parameters` (body, object) — Additional model-specific parameters. Refer to the [model guide](/guides/index-data-search-rerank-results#reranking-models) for available model parameters.

## Response

- `200` — OK
- `400` — Bad request. The request body included invalid request parameters.
- `401` — Unauthorized. Possible causes: Invalid API key.
- `500` — Internal server error.

## Related pages

- [Generate vectors](./inference-2026-07-generate-vectors.md)
- [List available models](./inference-2026-07-list-available-models.md)
- [Describe a model](./inference-2026-07-describe-a-model.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.