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.

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

# 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 theme={null}
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
```bash title="cURL"
curl --request POST \
  --url https://{index_host}/namespaces/{namespace}/documents/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 20,
  "prefix": "doc-"
}'
```

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

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Path Parameters

- `namespace` (path, string, required) — The namespace to list documents from.

## Headers

- `X-Pinecone-Api-Version` (header, string, required) — Required date-based version header

## Body

- `prefix` (body, string) — A prefix to filter document IDs. Only documents whose IDs begin with this prefix are returned.
- `limit` (body, integer) — The maximum number of documents to return per page. Defaults to 100.
- `pagination_token` (body, string) — A pagination token from a previous list response, used to retrieve the next page of results.

## Response

- `200` — A successful list 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.

## Related pages

- [Upsert documents](./database-2026-07-data-plane-upsert-documents.md)
- [Search documents](./database-2026-07-data-plane-search-documents.md)
- [Fetch documents](./database-2026-07-data-plane-fetch-documents.md)
- [Update documents](./database-2026-07-data-plane-update-documents.md)
- [Delete documents](./database-2026-07-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.