Fetch documents

• 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, holding limit documents per page (100 by default, 10000 at most). When there are more documents to return, the response includes a pagination token you can pass back as pagination_token to retrieve the next page. When no pagination token is returned, there are no more documents to 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"]
  }'

POST /namespaces/{namespace}/documents/fetch

• X-Pinecone-Api-Version (header, string, required) — Required date-based version header
• namespace (path, string, required) — The namespace to fetch documents from.

• ids (body, string[]) — A list of document IDs to fetch. Mutually exclusive with filter.
• filter (body, object) — 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.
• include_fields (body, string[]) — The document fields to return on each document. When omitted or empty, all fields are returned; ["*"] also returns every field.
• pagination_token (body, string) — A pagination token from a previous fetch response, used to retrieve the next page of matching documents. Only valid together with filter.
• limit (body, integer) — 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.

• 200 — A successful fetch response.
• 400 — Bad request. The request body included invalid request parameters.
• 401 — Unauthorized. Possible causes: missing or invalid API key.
• 4XX — An unexpected error response.
• 5XX — An unexpected error response.