IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Cluster reroute API Cluster stats API »
Elastic Docs ›Elasticsearch Guide [7.12] ›REST APIs ›Cluster APIs

Cluster state API

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Cluster state API

edit

Returns metadata about the state of the cluster.

Request

edit

GET /_cluster/state/<metrics>/<target>

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the monitor or manage cluster privilege to use this API.

Description

edit

The cluster state API allows access to metadata representing the state of the whole cluster. This includes information such as

  • the set of nodes in the cluster
  • all cluster-level settings
  • information about the indices in the cluster, including their mappings and settings
  • the locations of all the shards in the cluster.

The response is an internal representation of the cluster state and its format may change from version to version. If possible, you should obtain any information from the cluster state using the other, more stable, cluster APIs.

The response provides the cluster state itself, which can be filtered to only retrieve the parts of interest as described below.

The cluster’s cluster_uuid is also returned as part of the top-level response, in addition to the metadata section.

While the cluster is still forming, it is possible for the cluster_uuid to be _na_ as well as the cluster state’s version to be -1.

By default, the cluster state request is routed to the master node, to ensure that the latest cluster state is returned. For debugging purposes, you can retrieve the cluster state local to a particular node by adding local=true to the query string.

Path parameters

edit

The cluster state contains information about all the indices in the cluster, including their mappings, as well as templates and other metadata. This means it can sometimes be quite large. To avoid the need to process all this information you can request only the part of the cluster state that you need:

<metrics>

(Optional, string) A comma-separated list of the following options:

_all
Shows all metrics.
blocks
Shows the blocks part of the response.
master_node
Shows the elected master_node part of the response.
metadata
Shows the metadata part of the response. If you supply a comma separated list of indices, the returned output will only contain metadata for these indices.
nodes
Shows the nodes part of the response.
routing_nodes
Shows the routing_nodes part of the response.
routing_table
Shows the routing_table part of the response. If you supply a comma separated list of indices, the returned output will only contain the routing table for these indices.
version
Shows the cluster state version.
<target>

(Optional, string) Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported.

To target all data streams and indices in a cluster, omit this parameter or use _all or *.

Query parameters

edit
allow_no_indices

(Optional, Boolean) If true, the wildcard indices expression that resolves into no concrete indices will be ignored. (This includes _all string or when no indices have been specified).

Defaults to true.

expand_wildcards
(Optional, string) Whether to expand wildcard expression to concrete indices that are open, closed or both. Available options: open, closed, none, all.
flat_settings
(Optional, Boolean) If true, returns settings in flat format. Defaults to false.
ignore_unavailable
(Optional, Boolean) If true, unavailable indices (missing or closed) will be ignored.
local
(Optional, Boolean) If true, the request retrieves information from the local node only. Defaults to false, 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.
wait_for_metadata_version
(Optional, integer) Waits for the metadata version to be equal or greater than the specified metadata version.
wait_for_timeout
(Optional, time units) Specifies the maximum time to wait for wait_for_metadata_version before timing out.

Examples

edit

The following example returns only metadata and routing_table data for the foo and bar data streams or indices:

GET /_cluster/state/metadata,routing_table/foo,bar

The next example returns all available metadata for foo and bar:

GET /_cluster/state/_all/foo,bar

This example returns only the blocks metadata:

GET /_cluster/state/blocks
« Cluster reroute API Cluster stats API »