Get shard information Generally available

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

Query parameters

  • bytes string

    The unit used to display byte values.

    Values are b, kb, mb, gb, tb, or pb.

  • h string | array[string]

    List of columns to appear in the response. Supports simple wildcards.

  • s string | array[string]

    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.

  • master_timeout string

    Period to wait for a connection to the master node.

    Values are -1 or 0.

  • time string

    Unit used to display time values.

    Values are nanos, micros, ms, s, m, h, or d.

Responses

  • 200 application/json
    Hide response attributes Show response attributes 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.

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"
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" } ]