IMPORTANT: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.
cat allocation API
editcat allocation API
editProvides a snapshot of the number of shards allocated to each data node and their disk space.
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
monitor
ormanage
cluster privilege to use this API.
Path parameters
edit-
<node_id>
- (Optional, string) Comma-separated list of node IDs or names used to limit returned information.
Query parameters
edit-
bytes
- (Optional, byte size units) Unit used to display byte values.
-
format
- (Optional, string) Short version of the HTTP accept header. Valid values include JSON, YAML, etc.
-
local
-
(Optional, Boolean) If
true
, the request retrieves information from the local node only. Defaults tofalse
, which means information is retrieved from the master node. -
master_timeout
-
(Optional, time units)
Period to wait for a connection to the master node. If no response is received
before the timeout expires, the request fails and returns an error. Defaults to
30s
. -
h
- (Optional, string) Comma-separated list of column names to display.
-
help
-
(Optional, Boolean) If
true
, the response includes help information. Defaults tofalse
. -
s
- (Optional, string) Comma-separated list of column names or column aliases used to sort the response.
-
v
-
(Optional, Boolean) If
true
, the response includes column headings. Defaults tofalse
.
Response body
edit-
shards
- Number of primary and replica shards assigned to the node.
-
disk.indices
-
Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards.
-
disk.used
-
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 OS
- 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
- Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s OS. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
-
disk.total
- Total disk space for the node, including in-use and available space.
-
disk.percent
-
Total percentage of disk space in use. Calculated as
disk.used
/disk.total
. -
host
-
Network host for the node. Set using
network.host
. -
ip
- IP address and port for the node.
-
node
-
Name for the node. Set using
node.name
.
Examples
editGET /_cat/allocation?v=true
The API returns the following response:
shards disk.indices disk.used disk.avail disk.total disk.percent host ip node 1 260b 47.3gb 43.4gb 100.7gb 46 127.0.0.1 127.0.0.1 CSUXak2
This response shows a single shard is allocated to the one node available.