Type to search.

Get the cluster state

Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 1.3 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Get comprehensive information about the state of the cluster.

The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.

The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. You may need to consult the Elasticsearch source code to determine the precise meaning of the response.

By default the API will route requests to the elected master node since this node is the authoritative source of cluster states. You can also retrieve the cluster state held on the node handling the API request by adding the ?local=true query parameter.

Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. If you use this API repeatedly, your cluster may become unstable.

Warning

The response is a representation of an internal data structure. Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. Do not query this API using external monitoring tools. Instead, obtain the information you require using other more stable cluster APIs.

Required privileges

Cluster privileges monitor manage

Path parameters

metric union enum | enum[] optional

Limit the information returned to the specified metrics.

Supported values include:

  • _all: Shows all metrics.
  • version: Shows the cluster state version.
  • master_node: Shows the elected master_node part of the response.
  • blocks: Shows the blocks part of the response.
  • nodes: Shows the nodes 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.
  • 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.
  • routing_nodes: Shows the routing_nodes part of the response.
  • customs: Shows the customs part of the response, which includes custom cluster state information.

Leave it out to use /_cluster/state.

Values: _all version master_node blocks nodes metadata routing_table routing_nodes customs
index union string | string[] optional

A comma-separated list of index names; use _all or empty string to perform the operation on all indices

Leave it out to use /_cluster/state.

Query parameters

allow_no_indices boolean · default: true

A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

expand_wildcards union oneOf · default: open

Whether to expand wildcard expression to concrete indices that are open, closed or both

Supported values include:

  • all: Match any data stream or index, including hidden ones.
  • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
  • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
  • none: Wildcard expressions are not accepted.
Values: all open closed hidden none
flat_settings boolean · default: false

Return settings in flat format

ignore_unavailable boolean · default: false

If false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

local boolean · default: false deprecated

Return local information, do not retrieve the state from master node

master_timeout string · default: 30s

Timeout for waiting for new cluster state in case it is blocked

wait_for_metadata_version number

Wait for the metadata version to be equal or greater than the specified metadata version

wait_for_timeout string

The maximum time to wait for wait_for_metadata_version before timing out

Reference

Response

application/json

Response Type: object