- `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.

:::callout{intent="note"}
Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are supported in a filtered fetch, as they are in [search](/guides/database-data-plane-search-documents). A filtered [update](/guides/database-data-plane-update-documents) or [delete](/guides/database-data-plane-delete-documents) rejects them with a `400`.
:::

:::code-group
```python Python
# 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
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`

:::code-group
```json title="200"
{
  "documents": {
    "doc-1": {
      "_id": "doc-1",
      "title": "Introduction to Machine Learning"
    }
  },
  "namespace": "my-namespace",
  "usage": {
    "egress_bytes": 1024,
    "read_units": 5
  }
}
```

```json title="400"
{
  "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
}
```

```json title="4XX"
{
  "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
}
```

```json title="5XX"
{
  "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
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Path Parameters

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace` | `string` | - | The namespace to fetch documents from. |

#### Body

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ids?` | `string[]` | - | A list of document IDs to fetch. Mutually exclusive with filter. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filter?` | `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. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `include_fields?` | `string[]` | - | The document fields to return on each document. When omitted or empty, all fields are returned; ['*'] also returns every field. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pagination_token?` | `string` | - | A pagination token from a previous fetch response, used to retrieve the next page of matching documents. Only valid together with filter. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `limit?` | `integer` | `100` | 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 <= 10000. Example: 100 |

#### Response

`200` — A successful fetch response.

The response for the `fetch_documents` operation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `documents` | `object` | - | A map of document IDs to their fetched documents. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pagination?` | `object` | - |  |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `next` | `string` | - | Example: Tm90aGluZyB0byBzZWUgaGVyZQo= |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace` | `string` | - | The namespace the documents were fetched from: the request's namespace, or the alias's target namespace when the request named a namespace alias. Example: my-namespace |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | - | Usage information for the fetch_documents operation. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `read_units` | `integer` | - | The number of read units consumed by this operation. Example: 5 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `egress_bytes?` | `integer` | - | The billed egress for this response, in bytes. Measured on the encoded response payload. Required range: 0 <= x. Example: 1024 |
:::

## Related pages

- [Upsert documents](./database-data-plane-upsert-documents.md)
- [Search documents](./database-data-plane-search-documents.md)
- [List documents](./database-data-plane-list-documents.md)
- [Update documents](./database-data-plane-update-documents.md)
- [Delete documents](./database-data-plane-delete-documents.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.