# 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 'Api-Key: <api-key>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>' \
  --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"
  }
}'
```

```python title="Python"
import requests

url = "https://api.pinecone.io/rerank"

payload = {
  "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"
  }
}
headers = {
    "Api-Key": "<api-key>",
    "X-Pinecone-Api-Version": "<x-pinecone-api-version>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

```javascript title="JavaScript"
const options = {method: "POST", headers: {"Api-Key": "<api-key>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>", "Content-Type": "application/json"}, body: JSON.stringify({
  "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"
  }
})};

fetch("https://api.pinecone.io/rerank", options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php title="PHP"
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pinecone.io/rerank",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"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\"}}",
  CURLOPT_HTTPHEADER => [
    "Api-Key: <api-key>",
    "X-Pinecone-Api-Version: <x-pinecone-api-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go title="Go"
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinecone.io/rerank"

	payload := strings.NewReader("{\"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\"}}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Api-Key", "<api-key>")
	req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java title="Java"
HttpResponse<String> response = Unirest.post("https://api.pinecone.io/rerank")
  .header("Api-Key", "<api-key>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .header("Content-Type", "application/json")
  .body("{\"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\"}}")
  .asString();
```

```ruby title="Ruby"
require 'uri'
require 'net/http'

url = URI("https://api.pinecone.io/rerank")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Api-Key"] = '<api-key>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\"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\"}}"

response = http.request(request)
puts response.read_body
```
:::

:::code-group
```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
  }
}
```

```json title="400"
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Bad request. The request body included invalid request parameters."
  },
  "status": 400
}
```

```json title="401"
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}
```

```json title="500"
{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Body

Rerank documents for the given query

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | `string` | - | Example: bge-reranker-v2-m3 |

The [model](/guides/index-data-search-rerank-results#reranking-models) to use for reranking.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | `string` | - | The query to rerank documents against. Example: What is the capital of France? |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top_n?` | `integer` | - | The number of results to return sorted by relevance. Defaults to the number of inputs. Example: 5 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `return_documents?` | `boolean` | `true` | Whether to return the documents in the response. Example: true |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rank_fields?` | `string[]` | `['text']` |  |

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `documents` | `object[]` | - | The documents to rerank. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parameters?` | `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

The result of a reranking request.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | `string` | - | The model used to rerank documents. Example: bge-reranker-v2-m3 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | - | The reranked documents. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `integer` | - | The index position of the document from the original request. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `score` | `number` | - | The relevance of the document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance. Example: 0.5 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `document?` | `object` | - | Document for reranking |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | - | Usage statistics for the model inference. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rerank_units?` | `integer` | - | The number of rerank units consumed by this operation. Required range: 0 <= x. Example: 1 |
:::

## Related pages

- [Generate vectors](./inference-generate-vectors.md)
- [List available models](./inference-list-available-models.md)
- [Describe a model](./inference-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.