Get shard information Generally available
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
Query parameters
-
The unit used to display byte values.
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
List of columns to appear in the response. Supports simple wildcards.
-
List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
Period to wait for a connection to the master node.
Values are
-1
or0
. -
Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
GET /_cat/shards
Console
GET _cat/shards?format=json
resp = client.cat.shards( format="json", )
const response = await client.cat.shards({ format: "json", });
response = client.cat.shards( format: "json" )
$resp = $client->cat()->shards([ "format" => "json", ]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/shards?format=json"
Response examples (200)
A single data stream or index
A successful response from `GET _cat/shards?format=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 successful response from `GET _cat/shards/my-index-*?format=json`. It returns information for any data streams or indices beginning with `my-index-`.
[ { "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 successful response from `GET _cat/shards?format=json`. The `RELOCATING` value in the `state` column indicates the index shard is relocating.
[ { "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" } ]
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.
[ { "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" } ]
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.
[ { "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" } ]