Search with text

POST

records

namespaces

{namespace}

INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "inputs": {"text": "Disease prevention"},
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

# Search with a query vector and rerank the results
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "vector": {
                "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
            },
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "id": "rec1",
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

{
    "result": {
        "hits": [
            {
                "_id": "rec3",
                "_score": 0.004433765076100826,
                "fields": {
                    "category": "immune system",
                    "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
                }
            },
            {
                "_id": "rec4",
                "_score": 0.0029121784027665854,
                "fields": {
                    "category": "endocrine system",
                    "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
                }
            }
        ]
    },
    "usage": {
        "embed_total_tokens": 8,
        "read_units": 6,
        "rerank_units": 1
    }
}

INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "inputs": {"text": "Disease prevention"},
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

# Search with a query vector and rerank the results
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "vector": {
                "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
            },
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "id": "rec1",
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

{
    "result": {
        "hits": [
            {
                "_id": "rec3",
                "_score": 0.004433765076100826,
                "fields": {
                    "category": "immune system",
                    "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
                }
            },
            {
                "_id": "rec4",
                "_score": 0.0029121784027665854,
                "fields": {
                    "category": "endocrine system",
                    "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
                }
            }
        ]
    },
    "usage": {
        "embed_total_tokens": 8,
        "read_units": 6,
        "rerank_units": 1
    }
}

Authorizations

Api-Key

string

header

required

An API Key is required to call Pinecone APIs. Get yours from the console.

Path Parameters

namespace

string

required

The namespace to search.

Body

application/json

A search request for records in a specific namespace.

query

object

required

The query inputs to search with. Each request can contain only one of the following parameters: inputs, vector, or id.

query.top_k

integer

required

The number of similar records to return.

Example:

10

query.filter

object

The filter to apply. You can use vector metadata to limit your search. See Understanding metadata.

query.inputs

object

Example:

{ "text": "chunk_text" }

query.vector

object

query.vector.values

number[]

This is the vector data included in the request.

query.vector.sparse_values

number[]

The sparse embedding values.

Example:

[0.1, 0.2, 0.3]

query.vector.sparse_indices

integer[]

The sparse embedding indices.

Example:

[10, 3, 156]

query.id

string

The unique ID of the vector to be used as a query vector.

Maximum length: 512

Example:

"example-vector-1"

fields

string[]

The fields to return in the search results. If not specified, the response will include all fields.

Example:

["chunk_text"]

rerank

object

Parameters for reranking the initial search results.

rerank.model

string

required

The name of the reranking model to use.

Example:

"bge-reranker-v2-m3"

rerank.rank_fields

string[]

required

The field(s) to consider for reranking. If not provided, the default is ["text"].

The number of fields supported is model-specific.

Example:

["chunk_text", "title"]

rerank.top_n

integer

The number of top results to return after reranking. Defaults to top_k.

Example:

5

rerank.parameters

object

Additional model-specific parameters. Refer to the model guide for available model parameters.

Example:

{ "truncate": "END" }

rerank.query

string

The query to rerank documents against. If a specific rerank query is specified, it overwrites the query input that was provided at the top level.

Example:

"What is the capital of France?"

Response

200

application/json

A successful search namespace response.

The records search response.

result

object

required

usage

object

required

Was this page helpful?

Search with a vector Start import

INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "inputs": {"text": "Disease prevention"},
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

# Search with a query vector and rerank the results
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "vector": {
                "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
            },
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-04" \
  -d '{
        "query": {
            "id": "rec1",
            "top_k": 4,
        },
        "fields": ["category", "chunk_text"]
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
        }
     }'

{
    "result": {
        "hits": [
            {
                "_id": "rec3",
                "_score": 0.004433765076100826,
                "fields": {
                    "category": "immune system",
                    "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
                }
            },
            {
                "_id": "rec4",
                "_score": 0.0029121784027665854,
                "fields": {
                    "category": "endocrine system",
                    "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
                }
            }
        ]
    },
    "usage": {
        "embed_total_tokens": 8,
        "read_units": 6,
        "rerank_units": 1
    }
}

APIs

Database

Inference

Admin

SDKs

Architecture

Tools

Authorizations

Path Parameters

Body

Response