Get shard allocation information

GET /_cat/allocation/{node_id}
GET /_cat/allocation

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.

Path Parameters

node_id union NodeId | [] NodeId 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 CatAllocationColumns

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 disk.used du diskUsed disk.avail da diskAvail disk.total dt diskTotal disk.percent dp diskPercent host h ip node n node.role r role nodeRole

s union Names

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.

One of: Name or 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 Duration · default: 30s

Period to wait for a connection to the master node.

Response

application/json

Response Type: [] AllocationRecord

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 | string nullable: Sum of index write load forecasts; One of: number | string or string
disk.indices.forecast union ByteSize | string nullable: Sum of shard size forecasts
disk.indices union ByteSize | 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 ByteSize | 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 ByteSize | 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 ByteSize | string nullable: Total disk space for the node, including in-use and available space.
disk.percent union Percentage | string nullable: Total percentage of disk space in use. Calculated as disk.used / disk.total.
host union Host | string nullable: Network host for the node. Set using the network.host setting.
ip union Ip | 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

Examples

A successful response from GET /_cat/allocation?v=true&format=json. It shows a single shard is allocated to the one node available.

Request Console 1 / 7 languages

Console Kibana Dev Tools

GET /_cat/allocation?v=true&format=json

JavaScript Elasticsearch JavaScript Client

const response = await client.cat.allocation({
  v: "true",
  format: "json",
});

Python Elasticsearch Python Client

resp = client.cat.allocation(
    v=True,
    format="json",
)

curl Shell

curl -X GET "$ELASTICSEARCH_URL/_cat/allocation?v=true&format=json" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"

Java Elasticsearch Java Client

client.cat().allocation();

PHP Elasticsearch PHP Client

$resp = $client->cat()->allocation([
    "v" => "true",
    "format" => "json",
]);

Ruby Elasticsearch Ruby Client

response = client.cat.allocation(
  v: "true",
  format: "json"
)

Response

[
  {
    "shards": "1",
    "shards.undesired": "0",
    "write_load.forecast": "0.0",
    "disk.indices.forecast": "260b",
    "disk.indices": "260b",
    "disk.used": "47.3gb",
    "disk.avail": "43.4gb",
    "disk.total": "100.7gb",
    "disk.percent": "46",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "node": "CSUXak2",
    "node.role": "himrst"
  }
]

Required authorization

Path Parameters

Query Parameters { h , s , local , master_timeout , }

Response

Query Parameters