This page describes how to create, list, describe, and delete namespaces in serverless indexes.

​
Create a namespace

This feature is in early access and available only on the 2025-10 version of the API.
Namespaces are created automatically during upsert. However, you can also create namespaces ahead of time using the create_namespace operation. Specify a name for the namespace and, optionally, the metadata fields to index.
curl
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/namespaces" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-API-Version: 2025-10" \
  -d '{
        "name": "example-namespace",
        "schema": {
		  "fields": { 
            "document_id": {"filterable": true},
            "document_title": {"filterable": true},
            "chunk_number": {"filterable": true},
            "document_url": {"filterable": true},
            "created_at": {"filterable": true}
          }
        }
      }'
The response will look like the following:
curl
{
    "name": "example-namespace",
    "record_count": "0",
    "schema": {
        "fields": {
            "document_title": {
                "filterable": true
            },
            "document_url": {
                "filterable": true
            },
            "chunk_number": {
                "filterable": true
            },
            "document_id": {
                "filterable": true
            },
            "created_at": {
                "filterable": true
            }
        }
    }
}

​
List all namespaces in an index

Use the list_namespaces operation to list all namespaces in a serverless index. Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the limit parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a pagination_token that you can use to get the next batch of namespaces. When the response does not include a pagination_token, there are no more namespaces to return. 
# Not supported with pinecone["grpc"] extras installed
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

index = pc.Index(host="INDEX_HOST")

# Implicit pagination using a generator function
for namespace in index.list_namespaces():
    print(namespace.name, ":", namespace.record_count)

# Manual pagination
namespaces = index.list_namespaces_paginated(
    limit=2,
    pagination_token="eyJza2lwX3Bhc3QiOiIxMDEwMy0="
)

print(namespaces)
The response will look like the following: 
# Implicit pagination
example-namespace : 20000
example-namespace2 : 10500
example-namespace3 : 10000
...

# Manual pagination
{
    "namespaces": [
        {
            "name": "example-namespace",
            "record_count": "20000"
        },
        {
            "name": "example-namespace2",
            "record_count": "10500"
        }
    ],
    "pagination": {
        "next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }
}

​
Describe a namespace

Use the describe_namespace operation to get details about a namespace in a serverless index, including the total number of vectors in the namespace. 
# Not supported with pinecone["grpc"] extras installed
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

index = pc.Index(host="INDEX_HOST")

namespace = index.describe_namespace(namespace="example-namespace")

print(namespace)
The response will look like the following: 
{
    "name": "example-namespace",
    "record_count": "20000"
}

​
Delete a namespace

Use the delete_namespace operation to delete a namespace in a serverless index.
Deleting a namespace is irreversible. All data in the namespace is permanently deleted.
# Not supported with pinecone["grpc"] extras installed
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

index = pc.Index(host="INDEX_HOST")

index.delete_namespace(namespace="example-namespace")

​
Rename a namespace

Pinecone does not support renaming namespaces directly. Instead, you must delete the records in the namespace and upsert the records to a new namespace.

​
Move records to a new namespace

Pinecone does not support moving records between namespaces directly. Instead, you must delete the records in the old namespace and upsert the records to the new namespace.

​
Use the default namespace

To use the default namespace for upserts, queries, or other data operations, set the namespace parameter to __default__, for example: 
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

results = index.search(
    namespace="example-namespace", 
    query={
        "inputs": {"text": "Disease prevention"}, 
        "top_k": 2
    },
    fields=["category", "chunk_text"]
)

print(results)