[[cat-allocation]]
=== cat allocation API
++++
<titleabbrev>cat allocation</titleabbrev>
++++

[IMPORTANT]
====
cat APIs are only intended for human consumption using the command line or {kib}
console. They are _not_ intended for use by applications.
====

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


[[cat-allocation-api-request]]
==== {api-request-title}

`GET /_cat/allocation/<node_id>`

`GET /_cat/allocation`

[[cat-allocation-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.

[[cat-allocation-api-path-params]]
==== {api-path-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=node-id]

[[cat-allocation-api-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=bytes]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=http-format]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=local]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-h]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=help]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-v]

[[cat-allocation-api-response-body]]
==== {api-response-body-title}

`shards`::
Number of primary and replica shards assigned to the node.

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

`write_load.forecast`::
Sum of index write load forecasts

`disk.indices.forecast`::
Sum of shard size forecasts

`disk.indices`::
Disk space used by the node's shards. Does not include disk space for the
<<index-modules-translog,translog>> or unassigned shards.
+
IMPORTANT: This metric double-counts disk space for hard-linked files, such as
those created when <<indices-shrink-index,shrinking>>,
<<indices-split-index,splitting>>, or <<indices-clone-index,cloning>> an index.

`disk.used`::
+
--
Total disk space in use. {es} retrieves this metric from the node's operating
system (OS). The metric includes disk space for:

- {es}, including the <<index-modules-translog,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 {es}. {es} retrieves this metric from the node's
OS. <<disk-based-shard-allocation,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,`network.host`>>.

`ip`::
IP address and port for the node.

`node`::
Name for the node. Set using <<node-name,`node.name`>>.

`node.role`, `r`, `role`, `nodeRole`::
Node roles

[[cat-allocation-api-example]]
==== {api-examples-title}

[source,console,id=cat-allocation-example]
--------------------------------------------------
GET /_cat/allocation?v=true
--------------------------------------------------
// TEST[s/^/PUT test\n{"settings": {"number_of_replicas": 0}}\n/]

The API returns the following response:

[source,txt]
--------------------------------------------------
shards shards.undesired write_load.forecast disk.indices.forecast disk.indices disk.used disk.avail disk.total disk.percent host      ip        node    node.role
     1                0                 0.0                  260b         260b    47.3gb     43.4gb    100.7gb           46 127.0.0.1 127.0.0.1 CSUXak2 himrst
--------------------------------------------------
// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/ s/46/\\d+/]
// TESTRESPONSE[s/CSUXak2 himrst/.+/ non_json]

This response shows a single shard is allocated to the one node available.