Get shard information

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

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

Path Parameters

index union IndexName | [] IndexName optional

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.

Leave it out to use /_cat/shards.

Query Parameters

h union CatShardColumns

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.
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).
- 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 API.
- unassigned.for (or uf): Time at which the shard was requested to be unassigned in Coordinated Universal Time (UTC).
- 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 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 Names

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: Name or Name[]

master_timeout string Duration · default: 30s

The period to wait for a connection to the master node.

Response

application/json

Response Type: [] ShardsRecord

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.

Examples

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

Request Console 1 / 7 languages

Console Kibana Dev Tools

GET _cat/shards?format=json

JavaScript Elasticsearch JavaScript Client

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

Python Elasticsearch Python Client

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

curl Shell

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

Java Elasticsearch Java Client

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

PHP Elasticsearch PHP Client

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

Ruby Elasticsearch Ruby Client

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

Response

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

Required authorization

Path Parameters

Query Parameters { h , s , master_timeout , }

Response

Query Parameters