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


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-repo-dir}/rest-api/common-parms.asciidoc[tag=node-id]

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

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

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

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

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

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

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

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

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

[[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 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
--------------------------------------------------
// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/ s/46/\\d+/]
// TESTRESPONSE[s/CSUXak2/.+/ non_json]

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