Search with text (legacy Records API)

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.

This operation is part of the legacy Records API, which legacy integrated indexes require. For new work, create a document index with a string field that uses integrated embedding (embed or sparse_embed), and search it with the Documents API’s search_documents operation and an embed or sparse_embed scoring method.

Searching with text (inputs) is supported only for legacy integrated indexes; 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.

POST /records/namespaces/{namespace}/search

Python

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
# To get the host for an index, see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.index(host="INDEX_HOST")

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
search_with_text = index.search(
    namespace="example-namespace",
    inputs={"text": "Disease prevention"},
    top_k=4,
    fields=["category", "chunk_text"],
    rerank={
        "model": "bge-reranker-v2-m3",
        "top_n": 2,
        "rank_fields": ["chunk_text"],
    },
)
for hit in search_with_text.result.hits:
    print(hit.id, hit.score, hit.fields)

# Search with a query vector and rerank the results
search_with_vector = index.search(
    namespace="example-namespace",
    vector=[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"],
    },
)
for hit in search_with_vector.result.hits:
    print(hit.id, hit.score, hit.fields)

# Search with a record ID and rerank the results
search_with_id = index.search(
    namespace="example-namespace",
    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"],
    },
)
for hit in search_with_id.result.hits:
    print(hit.id, hit.score, hit.fields)

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
  }
}

Python

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
# To get the host for an index, see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.index(host="INDEX_HOST")

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
search_with_text = index.search(
    namespace="example-namespace",
    inputs={"text": "Disease prevention"},
    top_k=4,
    fields=["category", "chunk_text"],
    rerank={
        "model": "bge-reranker-v2-m3",
        "top_n": 2,
        "rank_fields": ["chunk_text"],
    },
)
for hit in search_with_text.result.hits:
    print(hit.id, hit.score, hit.fields)

# Search with a query vector and rerank the results
search_with_vector = index.search(
    namespace="example-namespace",
    vector=[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"],
    },
)
for hit in search_with_vector.result.hits:
    print(hit.id, hit.score, hit.fields)

# Search with a record ID and rerank the results
search_with_id = index.search(
    namespace="example-namespace",
    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"],
    },
)
for hit in search_with_id.result.hits:
    print(hit.id, hit.score, hit.fields)

Authorizations

Api-Key · string · header · required

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

Headers

X-Pinecone-Api-Version · string · default: 2026-07 · required

Required date-based version header

Path Parameters

namespace · string · required

The namespace to search.

Body

application/json

A search request for records in a specific namespace, for the legacy Records API's search_records operation.

query · object · required

.

Show child attributes

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.

Show child attributes

Response

200

application/json

A successful search namespace response.

The records search response.

result · object · required

Show child attributes

usage · object · required

Show child attributes

namespace · string · required

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"