Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

Search with text

Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

Searching with text is supported only for indexes with integrated embedding. Searching with a query vector or record ID is supported for all indexes.

For guidance and examples, see Search.

curl
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-10" \
  -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-10" \
  -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 record ID 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-10" \
  -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"]
        }
     }'
curl
{
    "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
    }
}

POST /records/namespaces/{namespace}/search

Authorizations

Section titled “Authorizations”
Api-Keystringrequired

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

Headers

Section titled “Headers”
X-Pinecone-Api-Versionstringrequired

Required date-based version header

Typestring
Default2025-10

Path Parameters

Section titled “Path Parameters”
namespacestringrequired

The namespace to search.

Typestring

Body

Section titled “Body”
queryobjectrequired

.

Typeobject
Show child attributes
top_kintegerrequired

The number of similar records to return.

Example: 10

Typeinteger
filter?object

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

inputs?object
vector?object
Show child attributes
values?number[]

This is the vector data included in the request.

Required string length: 1 - 20000

Typenumber[]
sparse_values?number[]

The sparse embedding values.

Typenumber[]
sparse_indices?integer[]

The sparse embedding indices.

Typeinteger[]
id?string

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

Required string length: 0 - 512. Example: example-vector-1

Typestring
match_terms?object

Specifies which terms must be present in the text of each search hit based on the specified strategy. The match is performed against the text field specified in the integrated index field_map configuration. Terms are normalized and tokenized into single tokens before matching, and order does not matter. Example: "match_terms": {"terms": ["animal", "CHARACTER", "donald Duck"], "strategy": "all"} will tokenize to ["animal", "character", "donald", "duck"], and would match "Donald F. Duck is a funny animal character" but would not match "A duck is a funny animal". Match terms filtering is supported only for sparse indexes with integrated embedding configured to use the pinecone-sparse-english-v0 model.

Show child attributes
strategy?string

The strategy for matching terms in the text. Currently, only all is supported, which means all specified terms must be present.

Typestring
terms?string[]

A list of terms that must be present in the text of each search hit based on the specified strategy.

Typestring[]
fields?string[]

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

Required string length: 0 - 100

Typestring[]
rerank?object

Parameters for reranking the initial search results.

Typeobject
Show child attributes
modelstringrequired

Example: bge-reranker-v2-m3

Typestring

The name of the reranking model to use.

rank_fieldsstring[]required

The field(s) to consider for reranking. If not provided, the default is ["text"]. The number of fields supported is model-specific.

top_n?integer

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

Example: 5

Typeinteger
parameters?object

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

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?

Typestring

Response

Section titled “Response”

200 — A successful search namespace response.

The records search response.

resultobjectrequired
Show child attributes
hitsobject[]required

The hits for the search document request.

Typeobject[]
Show child attributes
_idstringrequired

The record id of the search hit.

Typestring
_scorenumberrequired

The similarity score of the returned record.

Typenumber
fieldsobjectrequired

The selected record fields associated with the search hit.

Typeobject
usageobjectrequired
Show child attributes
read_unitsintegerrequired

The number of read units consumed by this operation.

Required range: 0 <= x. Example: 5

Typeinteger
embed_total_tokens?integer

The number of embedding tokens consumed by this operation.

Required range: 0 <= x. Example: 2

Typeinteger
rerank_units?integer

The number of rerank units consumed by this operation.

Required range: 0 <= x. Example: 1

Typeinteger
Suggest an edit

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

Export
Documentation menu