Get shard allocation information

  • GET /_cat/allocation/{node_id}
  • GET /_cat/allocation
Auth

Get a snapshot of the number of shards allocated to each data node and their disk space.

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

Cluster privileges monitor

Path parameters

node_id union string | string[] optional

A comma-separated list of node identifiers or names used to limit the returned information.

Leave it out to use /_cat/allocation.

Query parameters

h union oneOf

A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:

  • shards (or s): The number of shards on the node.
  • shards.undesired: The number of shards scheduled to be moved elsewhere in the cluster.
  • write_load.forecast (or wlf, writeLoadForecast): The sum of index write load forecasts.
  • disk.indices.forecast (or dif, diskIndicesForecast): The sum of shard size forecasts.
  • disk.indices (or di, diskIndices): The disk space used by Elasticsearch indices.
  • disk.used (or du, diskUsed): The total disk space used on the node.
  • disk.avail (or da, diskAvail): The available disk space on the node.
  • disk.total (or dt, diskTotal): The total disk capacity of all volumes on the node.
  • disk.percent (or dp, diskPercent): The percentage of disk space used on the node.
  • host (or h): IThe host of the node.
  • ip: The IP address of the node.
  • node (or n): The name of the node.
  • node.role (or r, role, nodeRole): The roles assigned to the node.
Values: shards s shards.undesired write_load.forecast wlf writeLoadForecast disk.indices.forecast dif diskIndicesForecast disk.indices di diskIndices
s union string | 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.

local boolean · default: false

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.

master_timeout string · default: 30s

Period to wait for a connection to the master node.

format string · default: text

Specifies the format to return the columnar data in, can be set to text, json, cbor, yaml, or smile.

help boolean · default: false

When set to true will output available columns. This option can't be combined with any other query string option.

v boolean · default: false

When set to true will enable verbose output.

bytes enum

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

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
<array> object[]
shards string

Number of primary and replica shards assigned to the node.

shards.undesired union string nullable

Amount of shards that are scheduled to be moved elsewhere in the cluster or -1 other than desired balance allocator is used

One of: string
write_load.forecast union number | string nullable

Sum of index write load forecasts

One of: number | string or string
disk.indices.forecast union number | string | string nullable

Sum of shard size forecasts

disk.indices union number | string | string nullable

Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards. IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.

disk.used union number | string | string nullable

Total disk space in use. Elasticsearch retrieves this metric from the node’s operating system (OS). The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node. Unlike disk.indices, this metric does not double-count disk space for hard-linked files.

disk.avail union number | string | string nullable

Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s operating system. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.

disk.total union number | string | string nullable

Total disk space for the node, including in-use and available space.

disk.percent union number | string | string nullable

Total percentage of disk space in use. Calculated as disk.used / disk.total.

host union string nullable

Network host for the node. Set using the network.host setting.

ip union string nullable

IP address and port for the node.

node string

Name for the node. Set using the node.name setting.

node.role union string nullable

Node roles

One of: string