> ## 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. # 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`](/reference/api/2026-07/control-plane/create_index) until `status.ready: true` (and, for `Dedicated` read capacity, `read_capacity.status.state: "Ready"`) before performing data plane operations. ```python Python theme={null} # 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.host ``` ```shell curl theme={null} PINECONE_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" ``` ## OpenAPI ````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /indexes/{index_name} openapi: 3.0.3 info: title: Pinecone Control 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://api.pinecone.io description: Production API endpoints security: - ApiKeyAuth: [] tags: - name: Manage Indexes description: Actions that manage indexes externalDocs: description: More Pinecone.io API docs url: https://docs.pinecone.io/introduction paths: /indexes/{index_name}: get: tags: - Manage Indexes summary: Describe an index description: Get a description of an index. operationId: describe_index parameters: - in: header name: X-Pinecone-Api-Version description: Required date-based version header required: true schema: default: 2026-07 type: string style: simple - in: path name: index_name description: The name of the index to be described. required: true schema: type: string example: test-index style: simple responses: '200': description: Configuration information and deployment status of the index. content: application/json: schema: $ref: '#/components/schemas/IndexModel' examples: serverless-dense: summary: A serverless dense vector index value: 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 serverless-fts: summary: A serverless full-text search index value: deletion_protection: disabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: article-search-d12e6e6.svc.us-east1-gcp.pinecone.io name: article-search read_capacity: mode: OnDemand status: state: Ready schema: fields: body: full_text_search: language: en stemming: true stop_words: true type: string title: full_text_search: language: en type: string status: ready: true state: Ready links: UpsertVector: operationId: upsert server: url: $response.body#/host UpdateVector: operationId: update server: url: $response.body#/host QueryVector: operationId: query server: url: $response.body#/host FetchVector: operationId: fetch server: url: $response.body#/host DeleteOneVector: operationId: delete1 server: url: $response.body#/host DeleteVector: operationId: delete server: url: $response.body#/host '401': description: 'Unauthorized. Possible causes: missing or invalid API key.' content: text/plain: schema: $ref: '#/components/schemas/UnauthorizedMessage' '404': description: Index not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: index-not-found: summary: Index not found value: error: code: NOT_FOUND message: Index example-index not found. status: 404 '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-server-error: summary: Internal server error value: error: code: UNKNOWN message: Internal server error status: 500 components: schemas: IndexModel: example: deletion_protection: disabled deployment: cloud: aws deployment_type: managed region: us-east-1 host: my-index-abc123.svc.pinecone.io name: my-index read_capacity: mode: OnDemand status: state: Ready schema: fields: embedding: dimension: 1536 metric: cosine type: dense_vector title: full_text_search: language: en stemming: false stop_words: false type: string status: ready: true state: Ready description: >- The IndexModel describes the configuration and status of a Pinecone index. type: object properties: name: example: example-index description: > The 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 '-'. type: string minLength: 1 maxLength: 45 host: example: semantic-search-c01b5b5.svc.us-west1-gcp.pinecone.io description: The URL address where the index is hosted. type: string private_host: example: semantic-search-c01b5b5.svc.private.us-west1-gcp.pinecone.io description: The private endpoint URL of an index. type: string status: example: ready: true state: Ready description: The current status of the index. type: object properties: ready: description: Whether the index is ready for use. type: boolean state: description: >- The current state of the index. Possible values: `Initializing`, `InitializationFailed`, `Failed`, `ScalingUp`, `ScalingDown`, `ScalingUpPodSize`, `Terminating`, `Ready`, or `Disabled`. x-enum: - Initializing - InitializationFailed - Failed - ScalingUp - ScalingDown - ScalingUpPodSize - Terminating - Ready - Disabled type: string required: - ready - state deployment: $ref: '#/components/schemas/IndexDeployment' read_capacity: $ref: '#/components/schemas/ReadCapacityResponse' source_collection: example: movie-embeddings description: The name of the collection this index was created from, if any. type: string source_backup_id: example: 670e8400-e29b-41d4-a716-446655440000 description: The ID of the backup this index was restored from, if any. type: string cmek_id: example: arn:aws:kms:us-east-1:123456789012:key/mrk-abc123 description: >- The ID of the customer-managed encryption key (CMEK) used to encrypt this index, if any. type: string schema: $ref: '#/components/schemas/IndexSchema' tags: $ref: '#/components/schemas/IndexTags' deletion_protection: $ref: '#/components/schemas/DeletionProtection' required: - name - host - status - deployment - schema - deletion_protection UnauthorizedMessage: example: Invalid API key description: >- The plain-text body of a `401` response. Authentication failures are rejected before the request reaches the API, so they carry a short message rather than an `ErrorResponse`. type: string ErrorResponse: example: error: code: INVALID_ARGUMENT message: >- Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen. status: 400 description: The response shape used for all error responses. type: object properties: status: example: 500 description: The HTTP status code of the error. type: integer error: example: code: INVALID_ARGUMENT message: >- Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen. description: Detailed information about the error that occurred. type: object properties: code: description: >- The error code. Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`, `FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, `PAYLOAD_TOO_LARGE`, or `UNPROCESSABLE_ENTITY`. x-enum: - OK - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - INTERNAL - FORBIDDEN - PAYMENT_REQUIRED - SERVICE_UNAVAILABLE - PAYLOAD_TOO_LARGE - UNPROCESSABLE_ENTITY type: string message: example: >- Index name must contain only lowercase alphanumeric characters or hyphens, and must not begin or end with a hyphen. description: A human-readable description of the error type: string details: description: >- Additional information about the error. This field is not guaranteed to be present. type: object required: - code - message required: - status - error IndexDeployment: description: >- The deployment configuration of a Pinecone index. The `deployment_type` field indicates which infrastructure model the index uses. - `pod`: Dedicated pod-based infrastructure. Suitable for workloads that require predictable performance. - `managed`: Serverless infrastructure managed by Pinecone, including full-text search indexes. Scales automatically; billed per usage. - `byoc`: Bring-your-own-compute. Runs in customer-managed infrastructure. discriminator: propertyName: deployment_type mapping: pod: $ref: '#/components/schemas/PodDeployment' managed: $ref: '#/components/schemas/ManagedDeployment' byoc: $ref: '#/components/schemas/ByocDeployment' oneOf: - $ref: '#/components/schemas/PodDeployment' - $ref: '#/components/schemas/ManagedDeployment' - $ref: '#/components/schemas/ByocDeployment' ReadCapacityResponse: description: Response containing read capacity configuration discriminator: propertyName: mode mapping: OnDemand: $ref: '#/components/schemas/ReadCapacityOnDemandSpecResponse' Dedicated: $ref: '#/components/schemas/ReadCapacityDedicatedSpecResponse' oneOf: - $ref: '#/components/schemas/ReadCapacityOnDemandSpecResponse' - $ref: '#/components/schemas/ReadCapacityDedicatedSpecResponse' IndexSchema: example: fields: embedding: dimension: 1536 metric: cosine type: dense_vector title: full_text_search: language: en stemming: false stop_words: false type: string description: >- The 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. type: object properties: fields: description: >- A 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. type: object additionalProperties: $ref: '#/components/schemas/IndexSchemaField' required: - fields IndexTags: nullable: true example: tag0: val0 tag1: val1 description: >- Custom 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. type: object additionalProperties: type: string DeletionProtection: description: >- Whether [deletion protection](http://docs.pinecone.io/guides/manage-data/manage-indexes#configure-deletion-protection) is enabled/disabled for the index. Possible values: `disabled` or `enabled`. default: disabled x-enum: - disabled - enabled type: string PodDeployment: example: deployment_type: pod environment: us-east1-gcp pod_type: p1.x1 replicas: 1 shards: 1 title: Pod-based description: Deployment configuration for a pod-based index. type: object properties: deployment_type: description: Identifies this as a pod-based deployment. Must be `pod`. type: string enum: - pod environment: example: us-east1-gcp description: The environment where the index is hosted. type: string replicas: description: >- The number of replicas. Replicas duplicate your index. They provide higher availability and throughput. Replicas can be scaled up or down as your needs change. default: 1 type: integer format: int32 minimum: 1 shards: description: >- The number of shards. Shards split your data across multiple pods so you can fit more data into an index. default: 1 type: integer format: int32 minimum: 1 pod_type: description: >- The type of pod to use. One of `s1`, `p1`, or `p2` appended with `.` and one of `x1`, `x2`, `x4`, or `x8`. default: p1.x1 type: string required: - deployment_type - environment - pod_type additionalProperties: false ManagedDeployment: example: cloud: aws deployment_type: managed region: us-east-1 title: Serverless description: >- Deployment configuration for a serverless (managed) index. Serverless indexes scale automatically and you are billed only for the resources you use. This deployment type also covers full-text search indexes, which are serverless under the hood. type: object properties: deployment_type: description: >- Identifies this as a managed (serverless) deployment. Must be `managed`. type: string enum: - managed cloud: example: aws description: |- The public cloud where the index is hosted. Possible values: `gcp`, `aws`, or `azure`. x-enum: - gcp - aws - azure type: string region: example: us-east-1 description: The region where the index is hosted. type: string environment: readOnly: true example: aped-4627-b74a description: >- The Pinecone environment hosting the index. Returned in responses; do not set it when creating an index. type: string required: - deployment_type - cloud - region additionalProperties: false ByocDeployment: example: deployment_type: byoc environment: aws-us-east-1-b921 title: BYOC description: Deployment configuration for a bring-your-own-compute (BYOC) index. type: object properties: deployment_type: description: Identifies this as a BYOC deployment. Must be `byoc`. type: string enum: - byoc environment: example: aws-us-east-1-b921 description: The BYOC environment where the index is hosted. type: string required: - deployment_type - environment additionalProperties: false ReadCapacityOnDemandSpecResponse: example: mode: OnDemand status: state: Ready title: On-demand type: object properties: mode: description: >- The 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. type: string status: $ref: '#/components/schemas/ReadCapacityStatus' required: - mode - status additionalProperties: false ReadCapacityDedicatedSpecResponse: example: dedicated: manual: replicas: 2 shards: 2 node_type: t1 scaling: Manual mode: Dedicated status: current_replicas: 2 current_shards: 2 state: Ready title: Dedicated type: object properties: mode: description: >- The 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. type: string dedicated: $ref: '#/components/schemas/ReadCapacityDedicatedConfig' status: $ref: '#/components/schemas/ReadCapacityStatus' required: - mode - dedicated - status additionalProperties: false IndexSchemaField: description: >- The configuration of a single field in the index schema. Most fields carry a `type` property that identifies the field type: - `dense_vector`: Fixed-dimension floating-point vectors for ANN search. - `sparse_vector`: Sparse vectors for keyword or hybrid search. - `semantic_text`: Text field backed by an integrated embedding model. - `string`: String field for full-text search or metadata filtering. - `string_list`: String array field. - `float`: Numeric field. - `integer`: Legacy numeric field from older indexes (pre-dating float normalization). Will not appear in new indexes. - `boolean`: Boolean field. Fields in older indexes may omit `type` entirely. These are legacy metadata fields from before typed schemas were introduced. anyOf: - $ref: '#/components/schemas/TypedIndexSchemaField' - $ref: '#/components/schemas/LegacyMetadataField' ReadCapacityStatus: description: >- The current status of factors affecting the read capacity of a serverless index type: object properties: state: description: >- The `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](https://docs.pinecone.io/reference/api/2026-07/control-plane/configure_index) - `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. x-enum: - Ready - Scaling - Migrating - Error type: string current_replicas: nullable: true description: >- The 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. type: integer format: int32 current_shards: nullable: true description: >- The 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. type: integer format: int32 error_message: description: >- An optional error message indicating any issues with your read capacity configuration type: string required: - state ReadCapacityDedicatedConfig: description: >- Configuration for dedicated read capacity. See [this guide](https://docs.pinecone.io/guides/index-data/dedicated-read-nodes) for more details on how to configure dedicated read capacity. type: object properties: node_type: description: >- The type of machines to use. Available options: `b1` and `t1`. `t1` includes increased processing power and memory. type: string scaling: description: The type of scaling strategy to use. type: string manual: $ref: '#/components/schemas/ScalingConfigManual' required: - node_type - scaling - manual TypedIndexSchemaField: title: Typed field description: >- A schema field that carries a `type` discriminator. This covers all field types in current use. See `IndexSchemaField` for the full union that also includes legacy untyped fields. discriminator: propertyName: type mapping: dense_vector: $ref: '#/components/schemas/DenseVectorField' sparse_vector: $ref: '#/components/schemas/SparseVectorField' semantic_text: $ref: '#/components/schemas/SemanticTextField' string: $ref: '#/components/schemas/ResponseStringField' string_list: $ref: '#/components/schemas/StringListField' float: $ref: '#/components/schemas/FloatField' integer: $ref: '#/components/schemas/IntegerField' boolean: $ref: '#/components/schemas/BooleanField' oneOf: - $ref: '#/components/schemas/DenseVectorField' - $ref: '#/components/schemas/SparseVectorField' - $ref: '#/components/schemas/SemanticTextField' - $ref: '#/components/schemas/ResponseStringField' - $ref: '#/components/schemas/StringListField' - $ref: '#/components/schemas/FloatField' - $ref: '#/components/schemas/IntegerField' - $ref: '#/components/schemas/BooleanField' LegacyMetadataField: example: filterable: true title: Legacy metadata description: >- A legacy metadata field from indexes created before typed schema fields were introduced. The original data type of the field (string, float, boolean, etc.) was not recorded. Only the `filterable` flag is available. This field type will not appear in new indexes; it may appear in responses for older indexes pending schema migration. type: object properties: filterable: description: Whether this field is indexed for metadata filtering. type: boolean required: - filterable additionalProperties: false ScalingConfigManual: description: The config to use for manual read capacity scaling. type: object properties: replicas: description: >- The number of replicas to use. Replicas duplicate the compute resources and data of an index, allowing higher query throughput and availability. Setting replicas to 0 disables the index but can be used to reduce costs while usage is paused. type: integer format: int32 minimum: 0 shards: description: >- The number of shards to use. Shards determine the storage capacity of an index, with each shard providing 250 GB of storage. type: integer format: int32 minimum: 1 required: - replicas - shards DenseVectorField: example: dimension: 1536 metric: cosine type: dense_vector title: Dense vector description: >- A dense vector field configuration. Stores fixed-dimension floating-point vectors for approximate nearest-neighbor (ANN) search. type: object properties: type: description: Identifies this as a dense vector field. Must be `dense_vector`. type: string enum: - dense_vector description: nullable: true description: >- Optional description for this field, at most 256 bytes. `null` in responses when none was set. type: string maxLength: 256 dimension: example: 1536 description: The number of dimensions in the dense vectors stored in this field. type: integer format: int32 minimum: 1 maximum: 20000 metric: example: cosine description: |- The distance metric used for similarity search. Possible values: `cosine`, `dotproduct`, or `euclidean`. x-enum: - cosine - dotproduct - euclidean type: string required: - type - dimension - metric SparseVectorField: example: type: sparse_vector title: Sparse vector description: >- A sparse vector field configuration. Stores sparse vectors for keyword or hybrid search. type: object properties: type: description: Identifies this as a sparse vector field. Must be `sparse_vector`. type: string enum: - sparse_vector description: nullable: true description: >- Optional description for this field, at most 256 bytes. `null` in responses when none was set. type: string maxLength: 256 required: - type SemanticTextField: example: model: multilingual-e5-large type: semantic_text title: Semantic text description: >- A semantic text field, as returned when describing an index created with an integrated embedding model. Backed by an integrated embedding model that embeds text at write and query time, enabling semantic similarity search without separate embedding calls. Cannot be declared when creating an index; use the create-for-model operation. type: object properties: type: description: Identifies this as a semantic text field. Must be `semantic_text`. type: string enum: - semantic_text description: nullable: true description: >- Optional description for this field, at most 256 bytes. `null` in responses when none was set. type: string maxLength: 256 model: example: multilingual-e5-large description: The name of the integrated embedding model to use for this field. type: string dimension: nullable: true example: 1024 description: >- The dimension of the vectors the model produces. `null` for models that produce sparse vectors. type: integer format: int32 metric: example: cosine description: >- The distance metric used for similarity search. Defaults to the model's preferred metric if not specified. Possible values: `cosine`, `dotproduct`, or `euclidean`. x-enum: - cosine - dotproduct - euclidean type: string write_parameters: nullable: true example: input_type: passage description: >- Model-specific parameters applied at write time, such as `input_type`. type: object read_parameters: nullable: true example: input_type: query description: >- Model-specific parameters applied at query time, such as `input_type`. type: object required: - type - model ResponseStringField: example: full_text_search: language: en stemming: false stop_words: false type: string title: String description: >- A string field as returned in index schema responses. String fields configured for full-text search include a `full_text_search` object; string fields used for metadata filtering only include a `filterable` flag. type: object properties: type: description: Identifies this as a string field. Must be `string`. type: string enum: - string description: nullable: true description: Optional description for this field. `null` when none was set. type: string full_text_search: description: >- Full-text search configuration. Present when the field is indexed for full-text search. type: object properties: language: example: en description: The language used for text analysis. Defaults to `en`. default: en type: string stemming: description: Whether stemming is applied during text analysis. type: boolean stop_words: description: >- Whether stop words are filtered during text analysis. Only `true` if `stemming: true`. type: boolean ngram: description: >- Character n-gram tokenization configuration. Present only when the field is configured for n-gram substring matching. type: object properties: min_gram: example: 2 description: Minimum n-gram length. type: integer max_gram: example: 3 description: Maximum n-gram length. type: integer prefix_only: description: >- Whether only prefix n-grams anchored at the start of the token are generated. type: boolean required: - min_gram - max_gram - prefix_only additionalProperties: false required: - language - stemming - stop_words additionalProperties: false filterable: description: Whether this field is indexed for metadata filtering. type: boolean required: - type StringListField: example: filterable: true type: string_list title: String array description: >- A string array field configuration. String array values are not declared in the index schema; include them as document metadata instead — they are indexed automatically at upsert time. type: object properties: type: description: Identifies this as a string array field. Must be `string_list`. type: string enum: - string_list description: nullable: true description: Optional description for this field. `null` when none was set. type: string filterable: description: Whether this field is indexed for metadata filtering. type: boolean required: - type FloatField: example: type: float title: Float description: >- A numeric (floating-point) field configuration. Numeric values are not declared in the index schema; include them as document metadata instead — they are indexed automatically at upsert time. type: object properties: type: description: Identifies this as a float field. Must be `float`. type: string enum: - float description: nullable: true description: Optional description for this field. `null` when none was set. type: string filterable: description: Whether this field is indexed for metadata filtering. type: boolean required: - type IntegerField: example: filterable: true type: integer title: Integer description: >- A legacy integer field configuration. Integer fields were used in older index schemas before numeric values were normalized to `float` at upsert time. New indexes will not produce this field type; it may appear in responses for indexes created before that normalization was introduced. type: object properties: type: description: Identifies this as an integer field. Must be `integer`. type: string enum: - integer description: nullable: true description: Optional description for this field. `null` when none was set. type: string filterable: description: Whether this field is indexed for metadata filtering. type: boolean required: - type BooleanField: example: type: boolean title: Boolean description: >- A boolean field configuration. Boolean values are not declared in the index schema; include them as document metadata instead — they are indexed automatically at upsert time. type: object properties: type: description: Identifies this as a boolean field. Must be `boolean`. type: string enum: - boolean description: nullable: true description: Optional description for this field. `null` when none was set. type: string filterable: description: Whether this field is indexed for metadata filtering. type: boolean required: - type 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/). ````