Returns up to 100 documents per page by default, in sorted order (bitwise "C" collation). Use the optional `prefix` parameter to limit results to documents whose IDs start with a given prefix. When there are more documents to return, the response includes a `pagination` token you can pass to retrieve the next page. When no `pagination` token is returned, there are no more documents to list.

:::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"

# List every document ID in the namespace.
# The SDK returns a paginator, so iterating it walks every page.
for document in index.documents.list(namespace=NAMESPACE):
    print(document._id)

# List only the IDs beginning with a prefix.
for document in index.documents.list(namespace=NAMESPACE, prefix="report-2026#"):
    print(document._id)
```

```shell curl
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"

# EXAMPLE REQUEST 1: List the first page of document IDs
curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "limit": 20
  }'

# EXAMPLE REQUEST 2: List only the IDs beginning with a prefix
curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "prefix": "report-2026#"
  }'

# EXAMPLE REQUEST 3: Retrieve the next page
curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "pagination_token": "Tm90aGluZyB0byBzZWUgaGVyZQo="
  }'
```
:::

`POST /namespaces/{namespace}/documents/list`

:::code-group
```json title="200"
{
  "documents": [
    {
      "_id": "doc-1"
    },
    {
      "_id": "doc-2"
    }
  ],
  "namespace": "my-namespace",
  "pagination": {
    "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
  },
  "usage": {
    "egress_bytes": 1024,
    "read_units": 1
  }
}
```

```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 list documents from. |

#### Body

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `prefix?` | `string` | - | A prefix to filter document IDs. Only documents whose IDs begin with this prefix are returned. Required string length: 0 - 512 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `limit?` | `integer` | `100` | The maximum number of documents to return per page. Defaults to 100. Required range: 1 <= x <= 100 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pagination_token?` | `string` | - | A pagination token from a previous list response, used to retrieve the next page of results. |

#### Response

`200` — A successful list response.

The response for the `list_documents` operation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `documents` | `object[]` | - | The listed documents, in sorted order by ID. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `_id` | `string` | - | The unique identifier of the document. Required string length: 1+ |
:::

| 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 listed 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 list_documents operation. |

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

| 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)
- [Fetch documents](./database-data-plane-fetch-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.