Skip to main content
Pinecone Docs

Search documentation

Type to search this documentation.

On this pageOverview

Rerank results

For guidance and examples, see Rerank results.

curl
PINECONE_API_KEY="YOUR_API_KEY"

curl https://api.pinecone.io/rerank \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2025-10" \
  -H "Api-Key: $PINECONE_API_KEY" \
-d '{
  "model": "bge-reranker-v2-m3",
  "query": "The tech company Apple is known for its innovative products like the iPhone.",
  "return_documents": true,
  "top_n": 4,
  "documents": [
    {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."},
    {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."},
    {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."},
    {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."}
  ],
  "parameters": {
    "truncate": "END"
  }
}'
curl
{
  "data":[
    {
      "index":2,
      "document":{
        "id":"vec3",
        "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."
      },
      "score":0.47654688
    },
    {
      "index":0,
      "document":{
        "id":"vec1",
        "text":"Apple is a popular fruit known for its sweetness and crisp texture."
      },
      "score":0.047963805
    },
    {
      "index":3,
      "document":{
        "id":"vec4",
        "text":"An apple a day keeps the doctor away, as the saying goes."
      },
      "score":0.007587992
    },
    {
      "index":1,
      "document":{
        "id":"vec2",
        "text":"Many people enjoy eating apples as a healthy snack."
      },
      "score":0.0006491712
    }
  ],
  "usage":{
    "rerank_units":1
  }
}

POST /rerank

  • X-Pinecone-Api-Version (header, string, required) — Required date-based version header
  • model (body, string, required) — The model 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.
  • documents (body, object[], required) — The documents to rerank.
  • parameters (body, object) — Additional model-specific parameters. Refer to the model guide for available model parameters.
  • 200 — OK
  • 400 — Bad request. The request body included invalid request parameters.
  • 401 — Unauthorized. Possible causes: Invalid API key.
  • 500 — Internal server error.
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu