> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get index stats
> Return statistics about the contents of an index, including the vector count per namespace, the number of dimensions, and the index fullness.
Serverless indexes scale automatically as needed, so index fullness is relevant only for pod-based indexes.
Index fullness is also relevant for [dedicated read nodes](/guides/index-data/dedicated-read-nodes#index-fullness). The response includes `memoryFullness` and `storageFullness` alongside `indexFullness`, which summarizes overall capacity usage. For serverless on-demand indexes, all three values are typically `0` because storage and compute scale automatically. For dedicated indexes, these values indicate when the index needs more capacity. See [Scale your index](/guides/index-data/dedicated-read-nodes#scale-your-index).
```shell curl theme={null}
# 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="YOUR_INDEX_HOST"
curl -X POST "https://$INDEX_HOST/describe_index_stats" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07"
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /describe_index_stats
openapi: 3.0.3
info:
title: Pinecone Data Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-07
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Vector Operations
- name: Bulk Operations
- name: Namespace Operations
- name: Document Operations
description: >-
Operations on documents in an index created with a document schema — one
that declares at least one full-text-searchable string field or a
`dense_vector` / `sparse_vector` field under a name other than the
reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
document schema. Indexes served by the vectors API — created from
`dimension`/`metric` on an earlier API version, or from a schema holding
only the reserved vector fields and metadata — and indexes served by the
records API — created with an integrated embedding model, whose schema
holds a single `semantic_text` field — reject every document operation
with `400` and name the API to use instead. A document index accepts only
the document operations; the vector data operations (upsert, query, fetch,
update, delete, list) reject it, while index stats and the namespace
operations remain available.
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/describe_index_stats:
post:
tags:
- Vector Operations
summary: Get index stats
description: >-
Return statistics about the contents of an index, including the vector
count per namespace, the number of dimensions, and the index fullness.
Serverless indexes scale automatically as needed, so index fullness is
relevant only for pod-based indexes.
operationId: describeIndexStats
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-07
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeIndexStatsRequest'
required: true
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/IndexDescription'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
'401':
description: 'Unauthorized. Possible causes: missing or invalid API key.'
content:
text/plain:
schema:
$ref: '#/components/schemas/UnauthorizedMessage'
4XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
5XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
components:
schemas:
DescribeIndexStatsRequest:
description: The request for the `describe_index_stats` operation.
type: object
properties:
filter:
description: >-
If this parameter is present, the operation only returns statistics
for vectors that satisfy the filter. See [Understanding
metadata](https://docs.pinecone.io/guides/index-data/indexing-overview#metadata).
Serverless and Starter indexes do not support filtering
`describe_index_stats` by metadata, and reject a request carrying a
non-empty filter.
type: object
IndexDescription:
example:
dimension: 1024
indexFullness: 0.4
namespaces:
'':
vectorCount: 50000
example-namespace-2:
vectorCount: 30000
totalVectorCount: 80000
description: The response for the `describe_index_stats` operation.
type: object
properties:
namespaces:
description: >-
A mapping for each namespace in the index from the namespace name to
a summary of its contents.
type: object
additionalProperties:
$ref: '#/components/schemas/NamespaceSummary'
dimension:
example: 1024
description: >-
The dimension of the indexed vectors. Not specified if `sparse`
index.
type: integer
format: int64
indexFullness:
example: 0.4
description: >-
The fullness of the index, reported to a granularity of 1% and
capped at `1.0`. Always `0` for indexes with on-demand read
capacity.
Serverless indexes scale automatically as needed, so index fullness
is relevant only for pod-based indexes.
The index fullness result may be inaccurate during pod resizing; to
get the status of a pod resizing process, use
[`describe_index`](https://docs.pinecone.io/reference/api/2024-10/control-plane/describe_index).
type: number
format: float
totalVectorCount:
example: 80000
description: >-
The total number of vectors in the index, regardless of whether a
metadata filter expression was passed
type: integer
format: int64
metric:
example: cosine
description: The metric used to measure similarity.
type: string
vectorType:
example: dense
description: The type of vectors stored in the index.
type: string
memoryFullness:
description: The amount of memory used by a dedicated index
type: number
format: float
storageFullness:
description: The amount of storage used by a dedicated index
type: number
format: float
rpcStatus:
description: >-
The error response shape returned by the vector and bulk operations.
Requests rejected by the authentication and rate-limiting layer before
they reach the service (`401`, and the `400`, `403`, and `429` it
produces) return a plain-text body instead.
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
UnauthorizedMessage:
example: Unauthorized
description: >-
The plain-text body of a `401` response. Authentication failures are
rejected before the request reaches the index, so they carry the message
`Unauthorized` rather than an error object.
type: string
NamespaceSummary:
description: A summary of the contents of a namespace.
type: object
properties:
vectorCount:
example: 50000
description: >-
The number of vectors stored in this namespace. Note that updates to
this field may lag behind updates to the underlying index and
corresponding query results, etc.
type: integer
format: int64
protobufAny:
type: object
properties:
typeUrl:
type: string
value:
type: string
format: byte
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````