List documents
List documents in a namespace.
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.
# 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)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
Parameters
Section titled “Parameters”X-Pinecone-Api-Version(header, string, required) — Required date-based version headernamespace(path, string, required) — The namespace to list documents from.
Request body
Section titled “Request 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.
Responses
Section titled “Responses”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.