Search
Search with text
Database
- Indexes
- Vectors
- Search
- Imports
- Backups
Inference
- Embed
- Rerank
Assistant
- Assistants
- Files
- Chat
- Evaluation
- Context snippets
Search
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 Query data.
POST
/
records
/
namespaces
/
{namespace}
/
search
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-01" \
-d '{
"query": {
"inputs": {"text": "Disease prevention"},
"top_k": 4,
},
"fields": ["category", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_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-01" \
-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", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_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-01" \
-d '{
"query": {
"id": "text": "rec1",
"top_k": 4,
},
"fields": ["category", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_text"]
}
}'
{
"result": {
"hits": [
{
"_id": "rec6",
"_score": 0.004433765076100826,
"fields": {
"category": "nutrition",
"source_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec8",
"_score": 0.0029121784027665854,
"fields": {
"category": "nutrition",
"source_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-01" \
-d '{
"query": {
"inputs": {"text": "Disease prevention"},
"top_k": 4,
},
"fields": ["category", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_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-01" \
-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", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_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-01" \
-d '{
"query": {
"id": "text": "rec1",
"top_k": 4,
},
"fields": ["category", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_text"]
}
}'
{
"result": {
"hits": [
{
"_id": "rec6",
"_score": 0.004433765076100826,
"fields": {
"category": "nutrition",
"source_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec8",
"_score": 0.0029121784027665854,
"fields": {
"category": "nutrition",
"source_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
Path Parameters
The namespace to search.
Body
application/json
A search request for records in a specific namespace.
The query inputs to search with. Each request can contain only one of the following parameters: inputs, vector, or id.
The number of similar records to return.
The filter to apply. You can use vector metadata to limit your search. See Understanding metadata.
The query text to search with. Searching with text is supported only for indexes with integrated embedding.
The unique ID of the vector to be used as a query vector.
Maximum length:
512The fields to return in the search results. If not specified, the response will include all fields.
Parameters for reranking the initial search results.
The name of the reranking model to use.
The field(s) to consider for reranking. If not provided, the default is ["text"].
The number of fields supported is model-specific.
The number of top results to return after reranking. Defaults to top_k.
Additional model-specific parameters. Refer to the model guide for available model parameters.
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.
Response
200
application/json
A successful search namespace response.
The matches found for the query, ordered from most similar to least similar.
The number of read units consumed by this operation.
Required range:
x > 0The number of embedding tokens consumed by this operation.
Required range:
x > 0The number of rerank units consumed by this operation.
Required range:
x > 0Was this page helpful?
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-01" \
-d '{
"query": {
"inputs": {"text": "Disease prevention"},
"top_k": 4,
},
"fields": ["category", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_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-01" \
-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", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_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-01" \
-d '{
"query": {
"id": "text": "rec1",
"top_k": 4,
},
"fields": ["category", "source_text"]
"rerank": {
"query": {"text": "Disease prevention"},
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["source_text"]
}
}'
{
"result": {
"hits": [
{
"_id": "rec6",
"_score": 0.004433765076100826,
"fields": {
"category": "nutrition",
"source_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec8",
"_score": 0.0029121784027665854,
"fields": {
"category": "nutrition",
"source_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
}
}