To fetch records from a namespace based on their IDs, use the fetch operation with the following parameters:
namespace: The namespace containing the records to fetch. To use the default namespace, set this to "__default__".
ids: The IDs of the records to fetch. Maximum of 1000.
For on-demand indexes, since vector values are retrieved from object storage, fetch operations may have increased latency. If you only need metadata or IDs, consider using the query operation with include_values set to false instead. See Decrease latency for more details.
from pinecone.grpc import PineconeGRPC as Pineconepc = Pinecone(api_key="YOUR_API_KEY")# To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-indexindex = pc.Index(host="INDEX_HOST")index.fetch(ids=["id-1", "id-2"], namespace="example-namespace")
The maximum number of matching records to return in a single response. Defaults to 100; maximum 10,000. To retrieve more than 10,000 matching records, paginate using paginationToken.
namespace
No
The namespace containing the records to fetch. If omitted or set to an empty string, defaults to the default namespace. To explicitly use the default namespace, set this to "__default__".
paginationToken
No
The next token value from the pagination object found in a previous response. Include this value to fetch the next page of results, or omit it to start from the beginning. Must be used with the same namespace and filter parameters that generated it — using an existing token with different parameters will return incorrect results.
For example, the following code fetches 2 records with a genre field set to Action/Adventure from the default namespace:
curl
# To get the unique host for an index,# see https://docs.pinecone.io/guides/manage-data/target-an-indexPINECONE_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: 2025-10" \ -d '{ "namespace": "__default__", "filter": {"genre": {"$eq": "Action/Adventure"}}, "limit": 2 }'
The response looks like this:
curl
{ "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=" }}
To fetch the next page of results, set paginationToken to the value of next. For example:
When there are more results available, the response includes a pagination object with a next token. When there are no more results, the response does not include a pagination object.
Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to check data freshness.
