Describe a namespace
Describe a namespace in a serverless index, including the total number of vectors in the namespace.
For guidance and examples, see Manage namespaces.
Note: This operation is not supported for pod-based indexes.
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="YOUR_INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE" # To target the default namespace, use "__default__".
curl "https://$INDEX_HOST/namespaces/$NAMESPACE" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07"GET /namespaces/{namespace}
{
"name": "example-namespace",
"record_count": "20000",
"schema": {
"fields": {
"description": {
"filterable": true
},
"genre": {
"filterable": true
},
"year": {
"filterable": true
}
}
},
"indexed_fields": {
"fields": [
"genre",
"year",
"author"
]
},
"size_bytes": "1048576"
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}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 describe. Must be ASCII, must not contain the NUL character, and must be 1-512 characters long. Use __default__ to describe the namespace that requests address when they omit a namespace.
Required string length: 1 - 512
Response
Section titled “Response”200 — A description of a namespace.
A description of a namespace, including the name and record count.
name?stringThe name of the namespace.
Example: example-namespace
record_count?stringThe total number of records in the namespace. A 64-bit integer, serialized as a decimal string.
Example: 20000
schema?objectSchema for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when schema is present, only fields which are present in the fields object with a filterable: true are indexed. Note that filterable: false is not currently supported.
Show child attributes
fields?objectA map of metadata field names to their configuration. The field name must be a valid metadata field name. The field name must be unique. At most 50 fields may be declared. Field names may not begin with $, which introduces a filter operator. When declared at index creation, names beginning with _ are also rejected (reserved for internal use).
indexed_fields?objectA list of all indexed metatadata fields in the namespace
Show child attributes
fields?string[]size_bytes?stringThe total size of the namespace's data, in bytes, as a 64-bit integer serialized as a decimal string. Approximate: data written before size tracking reads as 0, and recently deleted data may still be counted; compaction converges the value.
Example: 1048576