Delete documents
Delete documents from a namespace. Exactly one of ids, filter, or delete_all must be specified.
ids: Delete documents with the given IDs.filter: Delete every document matching a metadata filter expression. Text-match operators ($match_phrase,$match_all,$match_any) are not supported in a filtered delete; they are only supported in search. The response reportsmatched_records, the number of documents the filter matched.delete_all: Delete all documents in the namespace.
# 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"
# Delete by IDs
index.documents.delete(namespace=NAMESPACE, ids=["doc1", "doc2"])
# Delete by metadata filter
index.documents.delete(namespace=NAMESPACE, filter={"category": {"$eq": "news"}})
# Delete every document in the namespace
index.documents.delete(namespace=NAMESPACE, delete_all=True)PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: Delete by IDs
curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{ "ids": ["doc1", "doc2"] }'
# EXAMPLE REQUEST 2: Delete by metadata filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{ "filter": { "category": { "$eq": "news" } } }'
# EXAMPLE REQUEST 3: Delete all documents in a namespace
curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{ "delete_all": true }'POST /namespaces/{namespace}/documents/delete
{
"matched_records": 42
}{
"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
}{
"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
}{
"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
}{
"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
Section titled “Authorizations”Api-KeystringrequiredAn API Key is required to call Pinecone APIs. Get yours from the console.
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Path Parameters
Section titled “Path Parameters”namespacestringrequiredThe namespace to delete documents from.
ids?string[]A list of document IDs to delete. Mutually exclusive with filter and delete_all.
filter?objectA metadata filter expression selecting the documents to delete. Must not be empty; an empty filter is rejected rather than matching every document. To delete every document in the namespace, set delete_all. Text-match operators ($match_phrase, $match_all, $match_any) are not supported here, since documents are selected on metadata alone. Mutually exclusive with ids and delete_all.
delete_all?booleanIf true, delete all documents in the namespace. Mutually exclusive with ids and filter. false is treated as if the field were omitted.
Response
Section titled “Response”202 — The delete request was successfully accepted.
The response for the delete_documents operation.
matched_records?integerThe number of documents that matched filter when the delete was accepted. Only returned for a filtered delete, and omitted when the count could not be read in time; 0 means the filter matched no documents. The delete is applied asynchronously, so this is a point-in-time count rather than a guarantee of the number of documents ultimately deleted.
Example: 42