# Get shard information


**GET /_cat/shards/{index}**

**All methods and paths for this operation:**

<div>
                      <span class="operation-verb get">GET</span>
                      <span class="operation-path">/_cat/shards</span>
                      </div>
                    <div>
                      <span class="operation-verb get">GET</span>
                      <span class="operation-path">/_cat/shards/{index}</span>
                      </div>
                    

Get information about the shards in a cluster.
For data streams, the API returns information about the backing indices.
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.

## Required authorization

* Index privileges: `monitor`
* Cluster privileges: `monitor`



## Servers
- http://api.example.com: http://api.example.com ()


## Authentication methods
- Api key auth
- Basic auth
- Bearer auth


## Parameters

### Path parameters
- **index** (string | array[string])
  A comma-separated list of data streams, indices, and aliases used to limit the request.
  Supports wildcards (`*`).
  To target all data streams and indices, omit this parameter or use `*` or `_all`.

### Query parameters
- **h** (string | array[string])
  List of columns to appear in the response. Supports simple wildcards.

  Supported values include:
    - `completion.size` (or `cs`, `completionSize`): Size of completion. For example: `0b`.
    - `dataset.size`: Disk space used by the shard’s dataset, which may or may not be the size on
  disk, but includes space used by the shard on object storage. Reported as a size value for example: `5kb`.
    - `dense_vector.value_count` (or `dvc`, `denseVectorCount`): Number of indexed dense vectors.
    - `docs` (or `d`, `dc`): Number of documents in shard, for example: `25`.
    - `fielddata.evictions` (or `fe`, `fielddataEvictions`): Fielddata cache evictions, for example: `0`.
    - `fielddata.memory_size` (or `fm`, `fielddataMemory`): Used fielddata cache memory, for example: `0b`.
    - `flush.total` (or `ft`, `flushTotal`): Number of flushes, for example: `1`.
    - `flush.total_time` (or `ftt`, `flushTotalTime`): Time spent in flush, for example: `1`.
    - `get.current` (or `gc`, `getCurrent`): Number of current get operations, for example: `0`.
    - `get.exists_time` (or `geti`, `getExistsTime`): Time spent in successful gets, for example: `14ms`.
    - `get.exists_total` (or `geto`, `getExistsTotal`): Number of successful get operations, for example: `2`.
    - `get.missing_time` (or `gmti`, `getMissingTime`): Time spent in failed gets, for example: `0s`.
    - `get.missing_total` (or `gmto`, `getMissingTotal`): Number of failed get operations, for example: `1`.
    - `get.time` (or `gti`, `getTime`): Time spent in get, for example: `14ms`.
    - `get.total` (or `gto`, `getTotal`): Number of get operations, for example: `2`.
    - `id`: ID of the node, for example: `k0zy`.
    - `index` (or `i`, `idx`): Name of the index.
    - `indexing.delete_current` (or `idc`, `indexingDeleteCurrent`): Number of current deletion operations, for example: `0`.
    - `indexing.delete_time` (or `idti`, `indexingDeleteTime`): Time spent in deletions, for example: `2ms`.
    - `indexing.delete_total` (or `idto`, `indexingDeleteTotal`): Number of deletion operations, for example: `2`.
    - `indexing.index_current` (or `iic`, `indexingIndexCurrent`): Number of current indexing operations, for example: `0`.
    - `indexing.index_failed_due_to_version_conflict` (or `iifvc`, `indexingIndexFailedDueToVersionConflict`): Number of failed indexing operations due to version conflict, for example: `0`.
    - `indexing.index_failed` (or `iif`, `indexingIndexFailed`): Number of failed indexing operations, for example: `0`.
    - `indexing.index_time` (or `iiti`, `indexingIndexTime`): Time spent in indexing, such as for example: `134ms`.
    - `indexing.index_total` (or `iito`, `indexingIndexTotal`): Number of indexing operations, for example: `1`.
    - `ip`: IP address of the node, for example: `127.0.1.1`.
    - `merges.current` (or `mc`, `mergesCurrent`): Number of current merge operations, for example: `0`.
    - `merges.current_docs` (or `mcd`, `mergesCurrentDocs`): Number of current merging documents, for example: `0`.
    - `merges.current_size` (or `mcs`, `mergesCurrentSize`): Size of current merges, for example: `0b`.
    - `merges.total` (or `mt`, `mergesTotal`): Number of completed merge operations, for example: `0`.
    - `merges.total_docs` (or `mtd`, `mergesTotalDocs`): Number of merged documents, for example: `0`.
    - `merges.total_size` (or `mts`, `mergesTotalSize`): Size of current merges, for example: `0b`.
    - `merges.total_time` (or `mtt`, `mergesTotalTime`): Time spent merging documents, for example: `0s`.
    - `node` (or `n`): Node name, for example: `I8hydUG`.
    - `prirep` (or `p`, `pr`, `primaryOrReplica`): Shard type. Returned values are `primary` or `replica`.
    - `query_cache.evictions` (or `qce`, `queryCacheEvictions`): Query cache evictions, for example: `0`.
    - `query_cache.memory_size` (or `qcm`, `queryCacheMemory`): Used query cache memory, for example: `0b`.
    - `recoverysource.type` (or `rs`): Type of recovery source.
    - `refresh.time` (or `rti`, `refreshTime`): Time spent in refreshes, for example: `91ms`.
    - `refresh.total` (or `rto`, `refreshTotal`): Number of refreshes, for example: `16`.
    - `search.fetch_current` (or `sfc`, `searchFetchCurrent`): Current fetch phase operations, for example: `0`.
    - `search.fetch_time` (or `sfti`, `searchFetchTime`): Time spent in fetch phase, for example: `37ms`.
    - `search.fetch_total` (or `sfto`, `searchFetchTotal`): Number of fetch operations, for example: `7`.
    - `search.open_contexts` (or `so`, `searchOpenContexts`): Open search contexts, for example: `0`.
    - `search.query_current` (or `sqc`, `searchQueryCurrent`): Current query phase operations, for example: `0`.
    - `search.query_time` (or `sqti`, `searchQueryTime`): Time spent in query phase, for example: `43ms`.
    - `search.query_total` (or `sqto`, `searchQueryTotal`): Number of query operations, for example: `9`.
    - `search.scroll_current` (or `scc`, `searchScrollCurrent`): Open scroll contexts, for example: `2`.
    - `search.scroll_time` (or `scti`, `searchScrollTime`): Time scroll contexts held open, for example: `2m`.
    - `search.scroll_total` (or `scto`, `searchScrollTotal`): Completed scroll contexts, for example: `1`.
    - `segments.count` (or `sc`, `segmentsCount`): Number of segments, for example: `4`.
    - `segments.fixed_bitset_memory` (or `sfbm`, `fixedBitsetMemory`): Memory used by fixed bit sets for nested object field types and type filters for types referred in join fields, for example: `1.0kb`.
    - `segments.index_writer_memory` (or `siwm`, `segmentsIndexWriterMemory`): Memory used by index writer, for example: `18mb`.
    - `segments.memory` (or `sm`, `segmentsMemory`): Memory used by segments, for example: `1.4kb`.
    - `segments.version_map_memory` (or `svmm`, `segmentsVersionMapMemory`): Memory used by version map, for example: `1.0kb`.
    - `seq_no.global_checkpoint` (or `sqg`, `globalCheckpoint`): Global checkpoint.
    - `seq_no.local_checkpoint` (or `sql`, `localCheckpoint`): Local checkpoint.
    - `seq_no.max` (or `sqm`, `maxSeqNo`): Maximum sequence number.
    - `shard` (or `s`, `sh`): Name of the shard.
    - `dsparse_vector.value_count` (or `svc`, `sparseVectorCount`): Number of indexed [sparse vectors](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/sparse-vector).
    - `state` (or `st`): State of the shard. Returned values are:
  * `INITIALIZING`: The shard is recovering from a peer shard or gateway.
  * `RELOCATING`: The shard is relocating.
  * `STARTED`: The shard has started.
  * `UNASSIGNED`: The shard is not assigned to any node.
    - `store` (or `sto`): Disk space used by the shard, for example: `5kb`.
    - `suggest.current` (or `suc`, `suggestCurrent`): Number of current suggest operations, for example: `0`.
    - `suggest.time` (or `suti`, `suggestTime`): Time spent in suggest, for example: `0`.
    - `suggest.total` (or `suto`, `suggestTotal`): Number of suggest operations, for example: `0`.
    - `sync_id`: Sync ID of the shard.
    - `unassigned.at` (or `ua`): Time at which the shard became unassigned in [Coordinated Universal Time (UTC)](https://en.wikipedia.org/wiki/List_of_UTC_offsets).
    - `unassigned.details` (or `ud`): Details about why the shard became unassigned. This does not explain why the shard is currently unassigned. To understand why a shard
  is not assigned, use the [Cluster allocation explain](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-allocation-explain) API.
    - `unassigned.for` (or `uf`): Time at which the shard was requested to be unassigned in [Coordinated Universal Time (UTC)](https://en.wikipedia.org/wiki/List_of_UTC_offsets).
    - `unassigned.reason` (or `ur`): Indicates the reason for the last change to the state of this unassigned shard. This does not explain why the shard is currently unassigned.
  To understand why a shard is not assigned, use the [Cluster allocation explain](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-allocation-explain) API. Returned values include:

  * `ALLOCATION_FAILED`: Unassigned as a result of a failed allocation of the shard.
  * `CLUSTER_RECOVERED`: Unassigned as a result of a full cluster recovery.
  * `DANGLING_INDEX_IMPORTED`: Unassigned as a result of importing a dangling index.
  * `EXISTING_INDEX_RESTORED`: Unassigned as a result of restoring into a closed index.
  * `FORCED_EMPTY_PRIMARY`: The shard’s allocation was last modified by forcing an empty primary using the Cluster reroute API.
  * `INDEX_CLOSED`: Unassigned because the index was closed.
  * `INDEX_CREATED`: Unassigned as a result of an API creation of an index.
  * `INDEX_REOPENED`: Unassigned as a result of opening a closed index.
  * `MANUAL_ALLOCATION`: The shard’s allocation was last modified by the Cluster reroute API.
  * `NEW_INDEX_RESTORED`: Unassigned as a result of restoring into a new index.
  * `NODE_LEFT`: Unassigned as a result of the node hosting it leaving the cluster.
  * `NODE_RESTARTING`: Similar to `NODE_LEFT`, except that the node was registered as restarting using the Node shutdown API.
  * `PRIMARY_FAILED`: The shard was initializing as a replica, but the primary shard failed before the initialization completed.
  * `REALLOCATED_REPLICA`: A better replica location is identified and causes the existing replica allocation to be cancelled.
  * `REINITIALIZED`: When a shard moves from started back to initializing.
  * `REPLICA_ADDED`: Unassigned as a result of explicit addition of a replica.
  * `REROUTE_CANCELLED`: Unassigned as a result of explicit cancel reroute command.

- **s** (string | array[string])
  A comma-separated list of column names or aliases that determines the sort order.
  Sorting defaults to ascending and can be changed by setting `:asc`
  or `:desc` as a suffix to the column name.
- **master_timeout** (string)
  The period to wait for a connection to the master node.


## Responses
### 200


#### Body: application/json (array[object])
- **index** (string)
  The index name.
- **shard** (string)
  The shard name.
- **prirep** (string)
  The shard type: `primary` or `replica`.
- **state** (string)
  The shard state.
  Returned values include:
  `INITIALIZING`: The shard is recovering from a peer shard or gateway.
  `RELOCATING`: The shard is relocating.
  `STARTED`: The shard has started.
  `UNASSIGNED`: The shard is not assigned to any node.
- **docs** (string | null)
  The number of documents in the shard.
- **store** (string | null)
  The disk space used by the shard.
- **dataset** (string | null)
  total size of dataset (including the cache for partially mounted indices)
- **ip** (string | null)
  The IP address of the node.
- **id** (string)
  The unique identifier for the node.
- **node** (string | null)
  The name of node.
- **sync_id** (string)
  The sync identifier.
- **unassigned.reason** (string)
  The reason for the last change to the state of an unassigned shard.
  It does not explain why the shard is currently unassigned; use the cluster allocation explain API for that information.
  Returned values include:
  `ALLOCATION_FAILED`: Unassigned as a result of a failed allocation of the shard.
  `CLUSTER_RECOVERED`: Unassigned as a result of a full cluster recovery.
  `DANGLING_INDEX_IMPORTED`: Unassigned as a result of importing a dangling index.
  `EXISTING_INDEX_RESTORED`: Unassigned as a result of restoring into a closed index.
  `FORCED_EMPTY_PRIMARY`: The shard’s allocation was last modified by forcing an empty primary using the cluster reroute API.
  `INDEX_CLOSED`: Unassigned because the index was closed.
  `INDEX_CREATED`: Unassigned as a result of an API creation of an index.
  `INDEX_REOPENED`: Unassigned as a result of opening a closed index.
  `MANUAL_ALLOCATION`: The shard’s allocation was last modified by the cluster reroute API.
  `NEW_INDEX_RESTORED`: Unassigned as a result of restoring into a new index.
  `NODE_LEFT`: Unassigned as a result of the node hosting it leaving the cluster.
  `NODE_RESTARTING`: Similar to `NODE_LEFT`, except that the node was registered as restarting using the node shutdown API.
  `PRIMARY_FAILED`: The shard was initializing as a replica, but the primary shard failed before the initialization completed.
  `REALLOCATED_REPLICA`: A better replica location is identified and causes the existing replica allocation to be cancelled.
  `REINITIALIZED`: When a shard moves from started back to initializing.
  `REPLICA_ADDED`: Unassigned as a result of explicit addition of a replica.
  `REROUTE_CANCELLED`: Unassigned as a result of explicit cancel reroute command.
- **unassigned.at** (string)
  The time at which the shard became unassigned in Coordinated Universal Time (UTC).
- **unassigned.for** (string)
  The time at which the shard was requested to be unassigned in Coordinated Universal Time (UTC).
- **unassigned.details** (string)
  Additional details as to why the shard became unassigned.
  It does not explain why the shard is not assigned; use the cluster allocation explain API for that information.
- **recoverysource.type** (string)
  The type of recovery source.
- **completion.size** (string)
  The size of completion.
- **fielddata.memory_size** (string)
  The used fielddata cache memory.
- **fielddata.evictions** (string)
  The fielddata cache evictions.
- **query_cache.memory_size** (string)
  The used query cache memory.
- **query_cache.evictions** (string)
  The query cache evictions.
- **flush.total** (string)
  The number of flushes.
- **flush.total_time** (string)
  The time spent in flush.
- **get.current** (string)
  The number of current get operations.
- **get.time** (string)
  The time spent in get operations.
- **get.total** (string)
  The number of get operations.
- **get.exists_time** (string)
  The time spent in successful get operations.
- **get.exists_total** (string)
  The number of successful get operations.
- **get.missing_time** (string)
  The time spent in failed get operations.
- **get.missing_total** (string)
  The number of failed get operations.
- **indexing.delete_current** (string)
  The number of current deletion operations.
- **indexing.delete_time** (string)
  The time spent in deletion operations.
- **indexing.delete_total** (string)
  The number of delete operations.
- **indexing.index_current** (string)
  The number of current indexing operations.
- **indexing.index_time** (string)
  The time spent in indexing operations.
- **indexing.index_total** (string)
  The number of indexing operations.
- **indexing.index_failed** (string)
  The number of failed indexing operations.
- **merges.current** (string)
  The number of current merge operations.
- **merges.current_docs** (string)
  The number of current merging documents.
- **merges.current_size** (string)
  The size of current merge operations.
- **merges.total** (string)
  The number of completed merge operations.
- **merges.total_docs** (string)
  The nuber of merged documents.
- **merges.total_size** (string)
  The size of current merges.
- **merges.total_time** (string)
  The time spent merging documents.
- **refresh.total** (string)
  The total number of refreshes.
- **refresh.time** (string)
  The time spent in refreshes.
- **refresh.external_total** (string)
  The total nunber of external refreshes.
- **refresh.external_time** (string)
  The time spent in external refreshes.
- **refresh.listeners** (string)
  The number of pending refresh listeners.
- **search.fetch_current** (string)
  The current fetch phase operations.
- **search.fetch_time** (string)
  The time spent in fetch phase.
- **search.fetch_total** (string)
  The total number of fetch operations.
- **search.open_contexts** (string)
  The number of open search contexts.
- **search.query_current** (string)
  The current query phase operations.
- **search.query_time** (string)
  The time spent in query phase.
- **search.query_total** (string)
  The total number of query phase operations.
- **search.scroll_current** (string)
  The open scroll contexts.
- **search.scroll_time** (string)
  The time scroll contexts were held open.
- **search.scroll_total** (string)
  The number of completed scroll contexts.
- **segments.count** (string)
  The number of segments.
- **segments.memory** (string)
  The memory used by segments.
- **segments.index_writer_memory** (string)
  The memory used by the index writer.
- **segments.version_map_memory** (string)
  The memory used by the version map.
- **segments.fixed_bitset_memory** (string)
  The memory used by fixed bit sets for nested object field types and export type filters for types referred in `_parent` fields.
- **seq_no.max** (string)
  The maximum sequence number.
- **seq_no.local_checkpoint** (string)
  The local checkpoint.
- **seq_no.global_checkpoint** (string)
  The global checkpoint.
- **warmer.current** (string)
  The number of current warmer operations.
- **warmer.total** (string)
  The total number of warmer operations.
- **warmer.total_time** (string)
  The time spent in warmer operations.
- **path.data** (string)
  The shard data path.
- **path.state** (string)
  The shard state path.
- **bulk.total_operations** (string)
  The number of bulk shard operations.
- **bulk.total_time** (string)
  The time spent in shard bulk operations.
- **bulk.total_size_in_bytes** (string)
  The total size in bytes of shard bulk operations.
- **bulk.avg_time** (string)
  The average time spent in shard bulk operations.
- **bulk.avg_size_in_bytes** (string)
  The average size in bytes of shard bulk operations.


[Powered by Bump.sh](https://bump.sh)