---
type: api
title: Get shard information
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-cat-shards
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-cat-shards
products:
  - Elasticsearch
---

# Get shard information


## Paths

- `GET` `/_cat/shards/{index}`
- `GET` `/_cat/shards`

#### Path parameters

- `index` (union string | string[]) — optional, leave it out to use `/_cat/shards`
  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`.

## Description

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`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)

## Query string parameters

- `h` (union oneOf) — optional
  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.
  Values: `completion.size`, `cs`, `completionSize`, `dataset.size`, `dense_vector.value_count`, `dvc`, `denseVectorCount`, `docs`, `d`, `dc`, `fielddata.evictions`, `fe`, `fielddataEvictions`, `fielddata.memory_size`, `fm`, `fielddataMemory`, `flush.total`, `ft`, `flushTotal`, `flush.total_time`, `ftt`, `flushTotalTime`, `get.current`, `gc`, `getCurrent`, `get.exists_time`, `geti`, `getExistsTime`, `get.exists_total`, `geto`, `getExistsTotal`, `get.missing_time`, `gmti`, `getMissingTime`, `get.missing_total`, `gmto`, `getMissingTotal`, `get.time`, `gti`, `getTime`, `get.total`, `gto`, `getTotal`, `id`, `index`, `i`, `idx`, `indexing.delete_current`, `idc`, `indexingDeleteCurrent`, `indexing.delete_time`, `idti`, `indexingDeleteTime`, `indexing.delete_total`, `idto`, `indexingDeleteTotal`, `indexing.index_current`, `iic`, `indexingIndexCurrent`, `indexing.index_failed_due_to_version_conflict`, `iifvc`, `indexingIndexFailedDueToVersionConflict`, `indexing.index_failed`, `iif`, `indexingIndexFailed`, `indexing.index_time`, `iiti`, `indexingIndexTime`, `indexing.index_total`, `iito`, `indexingIndexTotal`, `ip`, `merges.current`, `mc`, `mergesCurrent`, `merges.current_docs`, `mcd`, `mergesCurrentDocs`, `merges.current_size`, `mcs`, `mergesCurrentSize`, `merges.total`, `mt`, `mergesTotal`, `merges.total_docs`, `mtd`, `mergesTotalDocs`, `merges.total_size`, `mts`, `mergesTotalSize`, `merges.total_time`, `mtt`, `mergesTotalTime`, `node`, `n`, `prirep`, `p`, `pr`, `primaryOrReplica`, `query_cache.evictions`, `qce`, `queryCacheEvictions`, `query_cache.memory_size`, `qcm`, `queryCacheMemory`, `recoverysource.type`, `rs`, `refresh.time`, `rti`, `refreshTime`, `refresh.total`, `rto`, `refreshTotal`, `search.fetch_current`, `sfc`, `searchFetchCurrent`, `search.fetch_time`, `sfti`, `searchFetchTime`, `search.fetch_total`, `sfto`, `searchFetchTotal`, `search.open_contexts`, `so`, `searchOpenContexts`, `search.query_current`, `sqc`, `searchQueryCurrent`, `search.query_time`, `sqti`, `searchQueryTime`, `search.query_total`, `sqto`, `searchQueryTotal`, `search.scroll_current`, `scc`, `searchScrollCurrent`, `search.scroll_time`, `scti`, `searchScrollTime`, `search.scroll_total`, `scto`, `searchScrollTotal`, `segments.count`, `sc`, `segmentsCount`, `segments.fixed_bitset_memory`, `sfbm`, `fixedBitsetMemory`, `segments.index_writer_memory`, `siwm`, `segmentsIndexWriterMemory`, `segments.memory`, `sm`, `segmentsMemory`, `segments.version_map_memory`, `svmm`, `segmentsVersionMapMemory`, `seq_no.global_checkpoint`, `sqg`, `globalCheckpoint`, `seq_no.local_checkpoint`, `sql`, `localCheckpoint`, `seq_no.max`, `sqm`, `maxSeqNo`, `shard`, `s`, `sh`, `dsparse_vector.value_count`, `svc`, `sparseVectorCount`, `state`, `st`, `store`, `sto`, `suggest.current`, `suc`, `suggestCurrent`, `suggest.time`, `suti`, `suggestTime`, `suggest.total`, `suto`, `suggestTotal`, `sync_id`, `unassigned.at`, `ua`, `unassigned.details`, `ud`, `unassigned.for`, `uf`, `unassigned.reason`, `ur`
- `s` (union oneOf) — optional
  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.
  One of: `string[]` or `string`
- `master_timeout` (string · default: 30s) — optional
  The period to wait for a connection to the master node.
- `format` (string · default: text) — optional
  Specifies the format to return the columnar data in, can be set to
`text`, `json`, `cbor`, `yaml`, or `smile`.
- `help` (boolean · default: false) — optional
  When set to `true` will output available columns. This option
can't be combined with any other query string option.
- `v` (boolean · default: false) — optional
  When set to `true` will enable verbose output.
- `bytes` (enum) — optional
  Sets the units for columns that contain a byte-size value.
Note that byte-size value units work in terms of powers of 1024. For instance `1kb` means 1024 bytes, not 1000 bytes.
If omitted, byte-size values are rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the numeric value of the column is as small as possible whilst still being at least `1.0`.
If given, byte-size values are rendered as an integer with no suffix, representing the value of the column in the chosen unit.
Values that are not an exact multiple of the chosen unit are rounded down.
  Values: `b`, `kb`, `mb`, `gb`, `tb`, `pb`
- `time` (enum) — optional
  Sets the units for columns that contain a time duration.
If omitted, time duration values are rendered with a suffix such as `ms`, `s`, `m` or `h`, chosen such that the numeric value of the column is as small as possible whilst still being at least `1.0`.
If given, time duration values are rendered as an integer with no suffix.
Values that are not an exact multiple of the chosen unit are rounded down.
  Values: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d`

## Response

`application/json`

Type: `object[]`

An array; each item has these fields:

- `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` (union string) — nullable
  The number of documents in the shard.
  One of: `string`
- `store` (union string) — nullable
  The disk space used by the shard.
  One of: `string`
- `dataset` (union string) — nullable
  total size of dataset (including the cache for partially mounted indices)
  One of: `string`
- `ip` (union string) — nullable
  The IP address of the node.
  One of: `string`
- `id` (string)
  The unique identifier for the node.
- `node` (union string) — nullable
  The name of node.
  One of: `string`
- `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.
## Code examples

#### Console

```console
GET _cat/shards?format=json
```

#### JavaScript

```javascript
const response = await client.cat.shards({
  format: "json",
});
```

#### Python

```python
resp = client.cat.shards(
    format="json",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/_cat/shards?format=json" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.cat().shards(s -> s);
```

#### PHP

```php
$resp = $client->cat()->shards([
    "format" => "json",
]);
```

#### Ruby

```ruby
response = client.cat.shards(
  format: "json"
)
```

## Response examples

#### A single data stream or index

A successful response from `GET _cat/shards?format=json`.

```json
[
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "p",
    "state": "STARTED",
    "docs": "3014",
    "store": "31.1mb",
    "dataset": "249b",
    "ip": "192.168.56.10",
    "node": "H5dfFeA"
  }
]
```

#### A wildcard pattern

A successful response from `GET _cat/shards/my-index-*?format=json`. It returns information for any data streams or indices beginning with `my-index-`.

```json
[
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "p",
    "state": "STARTED",
    "docs": "3014",
    "store": "31.1mb",
    "dataset": "249b",
    "ip": "192.168.56.10",
    "node": "H5dfFeA"
  }
]
```

#### A relocating shard

A successful response from `GET _cat/shards?format=json`. The `RELOCATING` value in the `state` column indicates the index shard is relocating.

```json
[
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "p",
    "state": "RELOCATING",
    "docs": "3014",
    "store": "31.1mb",
    "dataset": "249b",
    "ip": "192.168.56.10",
    "node": "H5dfFeA -> -> 192.168.56.30 bGG90GE"
  }
]
```

#### Shard states

A successful response from `GET _cat/shards?format=json`. Before a shard is available for use, it goes through an `INITIALIZING` state. You can use the cat shards API to see which shards are initializing.

```json
[
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "p",
    "state": "STARTED",
    "docs": "3014",
    "store": "31.1mb",
    "dataset": "249b",
    "ip": "192.168.56.10",
    "node": "H5dfFeA"
  },
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "r",
    "state": "INITIALIZING",
    "docs": "0",
    "store": "14.3mb",
    "dataset": "249b",
    "ip": "192.168.56.30",
    "node": "bGG90GE"
  }
]
```

#### Reasons for unassigned shards

A successful response from `GET _cat/shards?h=index,shard,prirep,state,unassigned.reason&format=json`. It includes the `unassigned.reason` column, which indicates why a shard is unassigned.

```json
[
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "p",
    "state": "STARTED",
    "unassigned.reason": "3014 31.1mb 192.168.56.10 H5dfFeA"
  },
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "r",
    "state": "STARTED",
    "unassigned.reason": "3014 31.1mb 192.168.56.30 bGG90GE"
  },
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "r",
    "state": "STARTED",
    "unassigned.reason": "3014 31.1mb 192.168.56.20 I8hydUG"
  },
  {
    "index": "my-index-000001",
    "shard": "0",
    "prirep": "r",
    "state": "UNASSIGNED",
    "unassigned.reason": "ALLOCATION_FAILED"
  }
]
```