# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"namespace": "__default__",
"filter": {"genre": {"$eq": "Action/Adventure"}},
"limit": 2
}'
{
"namespace": "example-namespace",
"pagination": {
"next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
},
"usage": {
"readUnits": 5
},
"vectors": {
"id-1": {
"id": "id-1",
"metadata": {
"genre": "documentary",
"year": 2019
},
"values": [
1,
1.5
]
},
"id-2": {
"id": "id-2",
"metadata": {
"genre": "comedy",
"year": 2019
},
"values": [
2,
1
]
}
}
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "aSDinaTvuI8gbWludGxpZnk="
}
]
}"Unauthorized"{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "aSDinaTvuI8gbWludGxpZnk="
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "aSDinaTvuI8gbWludGxpZnk="
}
]
}Vectors
Fetch records by metadata
Look up and return records by metadata from a single namespace. The returned records include the vector data and metadata. For guidance and examples, see Fetch data.
POST
/
vectors
/
fetch_by_metadata
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"namespace": "__default__",
"filter": {"genre": {"$eq": "Action/Adventure"}},
"limit": 2
}'
{
"namespace": "example-namespace",
"pagination": {
"next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
},
"usage": {
"readUnits": 5
},
"vectors": {
"id-1": {
"id": "id-1",
"metadata": {
"genre": "documentary",
"year": 2019
},
"values": [
1,
1.5
]
},
"id-2": {
"id": "id-2",
"metadata": {
"genre": "comedy",
"year": 2019
},
"values": [
2,
1
]
}
}
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "aSDinaTvuI8gbWludGxpZnk="
}
]
}"Unauthorized"{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "aSDinaTvuI8gbWludGxpZnk="
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "aSDinaTvuI8gbWludGxpZnk="
}
]
}# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"namespace": "__default__",
"filter": {"genre": {"$eq": "Action/Adventure"}},
"limit": 2
}'
Authorizations
Headers
Required date-based version header
Body
application/json
The request for the fetch_by_metadata operation.
Metadata filter expression to select vectors. See Understanding metadata.
Example:
{
"genre": { "$in": ["comedy", "documentary", "drama"] },
"year": { "$eq": 2019 }
}
The namespace to fetch records from.
Example:
"example-namespace"
The maximum number of records to return per page. Defaults to 100.
Required range:
1 <= x <= 10000Example:
12
Pagination token to continue a previous listing operation.
Example:
"Tm90aGluZyB0byBzZWUgaGVyZQo="
Response
A successful response.
The response for the fetch_by_metadata operation.
Was this page helpful?