Skip to main content
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.preview.index(name="articles")

NAMESPACE = "example-namespace"

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", ""))

// Status: 200 OK
{
  "documents": {
    "doc1": {
      "_id": "doc1",
      "title": "Machine learning in 2024",
      "body": "Machine learning models are revolutionizing natural language processing",
      "category": "technology"
    },
    "doc2": {
      "_id": "doc2",
      "title": "Vector databases",
      "body": "Vector databases enable fast similarity search across embeddings",
      "category": "technology"
    }
  },
  "namespace": "__default__",
  "usage": { "read_units": 2 }
}
Full-text search is in public preview and uses API version 2026-01.alpha. APIs may continue to evolve before general availability.
Fetches schema-defined documents by ID from a namespace.
Fetch is ID-only. The endpoint does not accept a filter parameter — text match operators ($match_phrase, $match_all, $match_any) and metadata filter expressions are rejected with a 400 error. To retrieve documents matching a metadata expression, use POST /namespaces/{namespace}/documents/search with a filter to get IDs, then fetch by ID.
include_fields is optional. When omitted, all stored fields on each document are returned. 
# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.preview.index(name="articles")

NAMESPACE = "example-namespace"

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", ""))

// Status: 200 OK
{
  "documents": {
    "doc1": {
      "_id": "doc1",
      "title": "Machine learning in 2024",
      "body": "Machine learning models are revolutionizing natural language processing",
      "category": "technology"
    },
    "doc2": {
      "_id": "doc2",
      "title": "Vector databases",
      "body": "Vector databases enable fast similarity search across embeddings",
      "category": "technology"
    }
  },
  "namespace": "__default__",
  "usage": { "read_units": 2 }
}

Authorizations

​
Api-Key
string
header
required

An API Key is required to call Pinecone APIs. Get yours from the console.

Headers

​
X-Pinecone-Api-Version
string
default:2026-01.alpha
required

Required date-based version header

Path Parameters

​
namespace
string
required

The namespace to fetch documents from.

Body

application/json

The request for the fetch_documents operation.

​
ids
string[]
required

A list of document IDs to fetch.

Required array length: 1 - 1000 elements
​
include_fields
string[]

The document fields to include in the response. If not specified, all fields are returned.

Response

A successful fetch response.

The response for the fetch_documents operation.

​
documents
object
required

A map of document IDs to their fetched documents.

​
namespace
string
required

The namespace the documents were fetched from.

Example:

"my-namespace"

​
usage
object
required

Usage information for the fetch_documents operation.

Example:
{ "read_units": 5 }