Describe an index
Get a description of an index.
Returns detailed information about a specific index, including its schema, status, host URL, and read capacity. Poll this endpoint after POST /indexes until status.ready: true (and, for Dedicated read capacity, read_capacity.status.state: "Ready") before performing data plane operations.
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index_model = pc.indexes.describe(name="articles")
print(index_model.status, index_model.schema)
host = index_model.hostPINECONE_API_KEY="YOUR_API_KEY"
curl "https://api.pinecone.io/indexes/articles" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07"GET /indexes/{index_name}
{
"deletion_protection": "disabled",
"deployment": {
"cloud": "aws",
"deployment_type": "managed",
"region": "us-east-1"
},
"host": "movie-recommendations-c01b5b5.svc.us-east1-gcp.pinecone.io",
"name": "movie-recommendations",
"read_capacity": {
"mode": "OnDemand",
"status": {
"state": "Ready"
}
},
"schema": {
"fields": {
"embedding": {
"dimension": 1536,
"metric": "cosine",
"type": "dense_vector"
}
}
},
"status": {
"ready": true,
"state": "Ready"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Index example-index not found."
},
"status": 404
}{
"error": {
"code": "UNKNOWN",
"message": "Internal server error"
},
"status": 500
}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”index_namestringrequiredThe name of the index to be described.
Response
Section titled “Response”200 — Configuration information and deployment status of the index.
The IndexModel describes the configuration and status of a Pinecone index.
namestringrequiredThe name of the index. Resource name must be 1-45 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or '-'.
Required string length: 1 - 45. Example: example-index
hoststringrequiredThe URL address where the index is hosted.
Example: semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io
private_host?stringThe private endpoint URL of an index.
Example: semantic-search-c01b5b5.svc.private.us-west1-gcp.pinecone.io
statusobjectrequiredThe current status of the index.
Show child attributes
readybooleanrequiredWhether the index is ready for use.
statestringrequiredThe current state of the index. Possible values: Initializing, InitializationFailed, Failed, ScalingUp, ScalingDown, ScalingUpPodSize, Terminating, Ready, or Disabled.
deploymentobjectrequiredDeployment configuration for a pod-based index.
Show child attributes
deployment_typeenum<string>requiredIdentifies this as a pod-based deployment. Must be pod.
Available options: pod
environmentstringrequiredThe environment where the index is hosted.
Example: us-east1-gcp
replicas?integerThe number of replicas. Replicas duplicate your index. They provide higher availability and throughput. Replicas can be scaled up or down as your needs change.
Required range: 1 <= x
shards?integerThe number of shards. Shards split your data across multiple pods so you can fit more data into an index.
Required range: 1 <= x
pod_typestringrequiredThe type of pod to use. One of s1, p1, or p2 appended with . and one of x1, x2, x4, or x8.
read_capacity?objectShow child attributes
modestringrequiredThe mode of the index. Possible values: OnDemand or Dedicated. Defaults to OnDemand. If set to Dedicated, dedicated.node_type, and dedicated.scaling must be specified.
statusobjectrequiredThe current status of factors affecting the read capacity of a serverless index
Show child attributes
statestringrequiredThe state describes the overall status of factors relating to the read capacity of an index. Available values: - Ready is the state most of the time - Scaling if the number of replicas or shards has been recently updated by calling the configure index endpoint - Migrating if the index is being migrated to a new node_type - Error if there is an error with the read capacity configuration. In that case, see error_message for more details.
current_replicas?integer | nullThe number of replicas. Each replica has dedicated compute resources and data storage. Increasing this number will increase the total throughput of the index. null for OnDemand indexes and for a Dedicated index that has not finished provisioning.
current_shards?integer | nullThe number of shards. Each shard has dedicated storage. Increasing shards alleviates index fullness. null for OnDemand indexes and for a Dedicated index that has not finished provisioning.
error_message?stringAn optional error message indicating any issues with your read capacity configuration
source_collection?stringThe name of the collection this index was created from, if any.
Example: movie-embeddings
source_backup_id?stringThe ID of the backup this index was restored from, if any.
Example: 670e8400-e29b-41d4-a716-446655440000
cmek_id?stringThe ID of the customer-managed encryption key (CMEK) used to encrypt this index, if any.
Example: arn:aws:kms:us-east-1:123456789012:key/mrk-abc123
schemaobjectrequiredThe schema of a Pinecone index. The schema defines the typed fields that documents in the index can contain, including vector fields, semantic text fields, and metadata fields.
Show child attributes
fieldsobjectrequiredA map of field names to their configurations. Indexes that are served by the vectors API — created with the reserved _values / _sparse_values schema, or created by an earlier API version from dimension, metric, and vector_type — report their vector fields under the reserved names _values (dense) and _sparse_values (sparse), and any metadata fields configured for filtering as legacy fields carrying only filterable. Dense vectors-API indexes always report both _values and _sparse_values, regardless of how they were created.
tags?object | nullCustom user tags added to an index, at most 20 per index. Keys must be 80 characters or less and alphanumeric, '', or '-'. Values must be 120 characters or less and consist of printable ASCII characters or spaces. To unset a key, set the value to be an empty string. null in responses when the index has no tags.
deletion_protectionstringrequiredWhether deletion protection is enabled/disabled for the index. Possible values: disabled or enabled.