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 (inputs) is supported only for indexes with integrated embedding; for any other index a text query is rejected with 400, and it is not available on BYOC indexes; reranking (rerank) is likewise unavailable on BYOC indexes. Searching with a query vector (vector) or a record ID (id) works on any index served by the vectors API.

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: 2026-07" \
  -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"]
        }
     }'

# 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: 2026-07" \
  -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"]
        }
     }'

# 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: 2026-07" \
  -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"]
        }
     }'

POST /records/namespaces/{namespace}/search

200
{
  "namespace": "example-namespace",
  "result": {
    "hits": [
      {
        "_id": "example-record-1",
        "_score": 0.9281134605407715,
        "fields": {
          "data": "your example text"
        }
      }
    ]
  },
  "usage": {
    "egress_bytes": 1024,
    "embed_total_tokens": 10,
    "read_units": 5
  }
}
400
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}
4XX
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}
5XX
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}

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
Default2026-07

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, from 1 to 10000.

Required range: 1 <= x <= 10000. 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.

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
strategystringrequired

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

Typestring
termsstring[]required

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.

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. Every returned record must contain each listed field; otherwise the request is rejected with 400. 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. Required when the search uses vector or id, since there is no query text to rerank against; omitting it in that case is rejected with 400.

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.

Required string length: 1+

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
egress_bytes?integer

The billed egress for this response, in bytes. Measured on the encoded response payload.

Required range: 0 <= x. Example: 1024

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
namespacestringrequired

The namespace that served the search: the request's namespace, or the alias's target namespace when the request named a namespace alias.

Example: example-namespace

Typestring
Suggest an edit

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

Export
Documentation menu