> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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, 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.
Text match operators (`$match_phrase`, `$match_all`, `$match_any`) aren't supported in a filtered fetch; they're only available in [search](/reference/api/2026-07/data-plane/search_documents).
```python Python theme={null}
# 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
```
```shell curl theme={null}
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"]
}'
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/fetch
openapi: 3.0.3
info:
title: Pinecone Data Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-07
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Vector Operations
- name: Bulk Operations
- name: Namespace Operations
- name: Document Operations
description: >-
Operations on documents in an index created with a document schema — one
that declares at least one full-text-searchable string field or a
`dense_vector` / `sparse_vector` field under a name other than the
reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
document schema. Indexes served by the vectors API — created from
`dimension`/`metric` on an earlier API version, or from a schema holding
only the reserved vector fields and metadata — and indexes served by the
records API — created with an integrated embedding model, whose schema
holds a single `semantic_text` field — reject every document operation
with `400` and name the API to use instead. A document index accepts only
the document operations; the vector data operations (upsert, query, fetch,
update, delete, list) reject it, while index stats and the namespace
operations remain available.
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/namespaces/{namespace}/documents/fetch:
post:
tags:
- Document Operations
summary: Fetch documents
description: >-
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, 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.
operationId: fetchDocuments
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-07
type: string
style: simple
- in: path
name: namespace
description: The namespace to fetch documents from.
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FetchDocumentsRequest'
examples:
by_ids:
summary: Fetch specific documents by ID
value:
ids:
- doc-1
- doc-2
include_fields:
- title
- content
by_filter:
summary: Fetch every document matching a metadata filter
value:
filter:
category:
$eq: news
include_fields:
- title
- content
by_filter_next_page:
summary: Fetch the next page of filter matches, 500 documents at a time
value:
filter:
category:
$eq: news
limit: 500
pagination_token: Tm90aGluZyB0byBzZWUgaGVyZQo=
required: true
responses:
'200':
description: A successful fetch response.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchDocumentsResponse'
examples:
by_ids:
summary: A fetch by document ID, which is never paginated
value:
documents:
doc-1:
_id: doc-1
title: Introduction to Machine Learning
namespace: my-namespace
usage:
read_units: 5
by_filter_mid_page:
summary: A page of filter matches with more results to follow
value:
documents:
doc-1:
_id: doc-1
title: Introduction to Machine Learning
namespace: my-namespace
pagination:
next: Tm90aGluZyB0byBzZWUgaGVyZQo=
usage:
read_units: 5
by_filter_last_page:
summary: >-
The final page of filter matches, with no `pagination` token
to follow
value:
documents:
doc-2:
_id: doc-2
title: Neural Networks in Practice
namespace: my-namespace
usage:
read_units: 5
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: 'Unauthorized. Possible causes: missing or invalid API key.'
content:
text/plain:
schema:
$ref: '#/components/schemas/UnauthorizedMessage'
4XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
5XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
FetchDocumentsRequest:
description: >-
The request for the `fetch_documents` operation. Exactly one of `ids` or
`filter` must be specified.
type: object
properties:
ids:
description: A list of document IDs to fetch. Mutually exclusive with `filter`.
type: array
items:
type: string
pattern: ^[\x01-\x7F]+$
minLength: 1
maxLength: 512
minItems: 1
maxItems: 1000
filter:
example:
category:
$eq: news
description: >-
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`.
type: object
minProperties: 1
include_fields:
description: >-
The document fields to return on each document. When omitted or
empty, all fields are returned; `["*"]` also returns every field.
type: array
items:
type: string
pagination_token:
description: >-
A pagination token from a previous fetch response, used to retrieve
the next page of matching documents. Only valid together with
`filter`.
type: string
limit:
example: 100
description: >-
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.
default: 100
type: integer
format: int32
minimum: 1
maximum: 10000
anyOf:
- required:
- ids
not:
required:
- pagination_token
- required:
- filter
not:
required:
- ids
- filter
FetchDocumentsResponse:
description: The response for the `fetch_documents` operation.
type: object
properties:
documents:
description: A map of document IDs to their fetched documents.
type: object
additionalProperties:
$ref: '#/components/schemas/FetchedDocumentRecord'
pagination:
$ref: '#/components/schemas/Pagination'
namespace:
example: my-namespace
description: The namespace the documents were fetched from.
type: string
usage:
$ref: '#/components/schemas/DocumentFetchUsage'
required:
- documents
- namespace
- usage
ErrorResponse:
example:
error:
code: INVALID_ARGUMENT
message: >-
No 'ids' or 'filter' provided in the document fetch request. Provide
at least one document ID in 'ids', or a metadata filter in 'filter'.
status: 400
description: >-
The error response shape returned by the records and documents
operations. The vector operations return `rpcStatus` instead. Requests
rejected by the authentication and rate-limiting layer before they reach
the service (`401`, and the `400`, `403`, and `429` it produces) return
a plain-text body on every operation.
type: object
properties:
status:
example: 400
description: The HTTP status code of the error.
type: integer
error:
description: Detailed information about the error that occurred.
type: object
properties:
code:
example: INVALID_ARGUMENT
description: >-
The error code.
Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
`DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
`PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
`FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
`FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, or
`PAYLOAD_TOO_LARGE`.
x-enum:
- OK
- UNKNOWN
- INVALID_ARGUMENT
- DEADLINE_EXCEEDED
- NOT_FOUND
- ALREADY_EXISTS
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- INTERNAL
- FORBIDDEN
- PAYMENT_REQUIRED
- SERVICE_UNAVAILABLE
- PAYLOAD_TOO_LARGE
type: string
message:
example: >-
No 'ids' or 'filter' provided in the document fetch request.
Provide at least one document ID in 'ids', or a metadata filter
in 'filter'.
description: >-
A human-readable description of the error, including how to
correct the request where possible.
type: string
required:
- code
- message
required:
- status
- error
UnauthorizedMessage:
example: Unauthorized
description: >-
The plain-text body of a `401` response. Authentication failures are
rejected before the request reaches the index, so they carry the message
`Unauthorized` rather than an error object.
type: string
FetchedDocumentRecord:
example:
_id: doc-1
content: Machine learning is a subset of artificial intelligence.
title: Introduction to Machine Learning
description: A fetched document containing its ID and field values.
type: object
properties:
_id:
description: The unique identifier of the document.
type: string
minLength: 1
required:
- _id
additionalProperties: true
Pagination:
type: object
properties:
next:
example: Tm90aGluZyB0byBzZWUgaGVyZQo=
type: string
required:
- next
DocumentFetchUsage:
example:
read_units: 5
description: Usage information for the `fetch_documents` operation.
type: object
properties:
read_units:
example: 5
description: The number of read units consumed by this operation.
type: integer
format: int32
required:
- read_units
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````