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.
# 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-04" \
-d '{
"namespace": "__default__",
"filter": {"genre": {"$eq": "Action/Adventure"}},
"limit": 2
}'{
"vectors": {
"0": {
"id": "0",
"values": [
0.0234527588, 0.0291595459 ...
],
"metadata": {
"box-office": 2923706026,
"genre": "Action/Adventure",
"summary": "On the alien world of Pandora, paraplegic Marine Jake Sully uses an avatar to walk again and becomes torn between his mission and protecting the planet's indigenous Na'vi people. The film stars Sam Worthington, Zoe Saldana, and Sigourney Weaver.",
"title": "Avatar",
"year": 2009
}
},
"1": {
"id": "1",
"values": [
0.0397644043, 0.013053894, ...
],
"metadata": {
"box-office": 2799439100,
"genre": "Action/Adventure",
"summary": "In the aftermath of Thanos wiping out half of the universe, the remaining Avengers assemble once more to undo the chaos, leading to a time-traveling adventure. Stars Robert Downey Jr., Chris Evans, and Scarlett Johansson.",
"title": "Avengers: Endgame",
"year": 2019
}
}
},
"namespace": "__default__",
"usage": {
"readUnits": 1
},
"pagination": {
"next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
}
}POST /vectors/fetch_by_metadata
Parameters
Section titled “Parameters”X-Pinecone-Api-Version(header, string, required) — Required date-based version header
Request body
Section titled “Request body”namespace(body, string) — The namespace to fetch records from.filter(body, object) — Metadata filter expression to select vectors. See Understanding metadata.limit(body, integer) — Max number of vectors to return.paginationToken(body, string) — Pagination token to continue a previous listing operation.
Responses
Section titled “Responses”200— A successful response.400— Bad request. The request body included invalid request parameters.4XX— An unexpected error response.5XX— An unexpected error response.