# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# Fetch by IDs
response = index.documents.fetch(
namespace=NAMESPACE,
ids=["doc1", "doc2"],
include_fields=["title", "body", "category"],
)
for doc_id, doc in response.documents.items():
print(doc_id, getattr(doc, "title", ""))
# Fetch by metadata filter, paging through all matches
pagination_token = None
while True:
response = index.documents.fetch(
namespace=NAMESPACE,
filter={"category": {"$eq": "news"}},
include_fields=["title", "body", "category"],
pagination_token=pagination_token,
)
for doc_id, doc in response.documents.items():
print(doc_id, getattr(doc, "title", ""))
pagination = getattr(response, "pagination", None)
if not pagination or not getattr(pagination, "next", None):
break
pagination_token = pagination.next
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: Fetch by IDs
curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"ids": ["doc1", "doc2"],
"include_fields": ["title", "body", "category"]
}'
# EXAMPLE REQUEST 2: Fetch by metadata filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"filter": { "category": { "$eq": "news" } },
"include_fields": ["title", "body", "category"]
}'
{
"documents": {
"doc-1": {
"_id": "doc-1",
"title": "Introduction to Machine Learning"
}
},
"namespace": "my-namespace",
"usage": {
"read_units": 5
}
}Documents
Fetch documents
Fetch documents from a namespace. Returns the specified fields for each document. Exactly one of ids or filter must be specified.
ids: Fetch the documents with the given IDs.filter: Fetch every document matching a metadata filter expression. Results are returned a page at a time, holdinglimitdocuments per page (100 by default, 10000 at most). When there are more documents to return, the response includes apaginationtoken you can pass back aspagination_tokento retrieve the next page. When nopaginationtoken is returned, there are no more documents to fetch.
POST
/
namespaces
/
{namespace}
/
documents
/
fetch
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# Fetch by IDs
response = index.documents.fetch(
namespace=NAMESPACE,
ids=["doc1", "doc2"],
include_fields=["title", "body", "category"],
)
for doc_id, doc in response.documents.items():
print(doc_id, getattr(doc, "title", ""))
# Fetch by metadata filter, paging through all matches
pagination_token = None
while True:
response = index.documents.fetch(
namespace=NAMESPACE,
filter={"category": {"$eq": "news"}},
include_fields=["title", "body", "category"],
pagination_token=pagination_token,
)
for doc_id, doc in response.documents.items():
print(doc_id, getattr(doc, "title", ""))
pagination = getattr(response, "pagination", None)
if not pagination or not getattr(pagination, "next", None):
break
pagination_token = pagination.next
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: Fetch by IDs
curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"ids": ["doc1", "doc2"],
"include_fields": ["title", "body", "category"]
}'
# EXAMPLE REQUEST 2: Fetch by metadata filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"filter": { "category": { "$eq": "news" } },
"include_fields": ["title", "body", "category"]
}'
{
"documents": {
"doc-1": {
"_id": "doc-1",
"title": "Introduction to Machine Learning"
}
},
"namespace": "my-namespace",
"usage": {
"read_units": 5
}
}Text match operators (
$match_phrase, $match_all, $match_any) aren’t supported in a filtered fetch; they’re only available in search.# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# Fetch by IDs
response = index.documents.fetch(
namespace=NAMESPACE,
ids=["doc1", "doc2"],
include_fields=["title", "body", "category"],
)
for doc_id, doc in response.documents.items():
print(doc_id, getattr(doc, "title", ""))
# Fetch by metadata filter, paging through all matches
pagination_token = None
while True:
response = index.documents.fetch(
namespace=NAMESPACE,
filter={"category": {"$eq": "news"}},
include_fields=["title", "body", "category"],
pagination_token=pagination_token,
)
for doc_id, doc in response.documents.items():
print(doc_id, getattr(doc, "title", ""))
pagination = getattr(response, "pagination", None)
if not pagination or not getattr(pagination, "next", None):
break
pagination_token = pagination.next
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: Fetch by IDs
curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"ids": ["doc1", "doc2"],
"include_fields": ["title", "body", "category"]
}'
# EXAMPLE REQUEST 2: Fetch by metadata filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"filter": { "category": { "$eq": "news" } },
"include_fields": ["title", "body", "category"]
}'
Authorizations
Headers
Required date-based version header
Path Parameters
The namespace to fetch documents from.
Body
application/json
- Option 1
- Option 2
The request for the fetch_documents operation. Exactly one of ids or filter must be specified.
A list of document IDs to fetch. Mutually exclusive with filter.
Required array length:
1 - 1000 elementsRequired string length:
1 - 512Pattern:
^[\x01-\x7F]+$A metadata filter expression selecting the documents to fetch. Must not be empty; an empty filter is rejected rather than matching every document. Mutually exclusive with ids.
Example:
{ "category": { "$eq": "news" } }
The document fields to return on each document. When omitted or empty, all fields are returned; ["*"] also returns every field.
A pagination token from a previous fetch response, used to retrieve the next page of matching documents. Only valid together with filter.
The maximum number of documents to return per page. Only applies to a fetch by filter; a fetch by ids is already bounded by ids and ignores an in-range value, but a value outside 1-10000 is rejected on either form. Defaults to 100.
Required range:
1 <= x <= 10000Example:
100
Response
A successful fetch response.
The response for the fetch_documents operation.
A map of document IDs to their fetched documents.
Show child attributes
Show child attributes
The namespace the documents were fetched from.
Example:
"my-namespace"
Usage information for the fetch_documents operation.
Show child attributes
Show child attributes
Example:
{ "read_units": 5 }
Show child attributes
Show child attributes
Was this page helpful?