This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« cat fielddata API cat indices API »
Elastic Docs ›Elasticsearch Guide [8.16] ›REST APIs ›Compact and aligned text (CAT) APIs

cat health API

edit

cat health API

edit

cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API.

Returns the health status of a cluster, similar to the cluster health API.

Request

edit

GET /_cat/health

Prerequisites

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

Description

edit

You can use the cat health API to get the health status of a cluster.

This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats:

  • HH:MM:SS, which is human-readable but includes no date information.
  • Unix epoch time, which is machine-sortable and includes date information. This is useful for cluster recoveries that take multiple days.

You can use the cat health API to verify cluster health across multiple nodes. See Example across nodes.

You also can use the API to track the recovery of a large cluster over a longer period of time. See Example with a large cluster.

Query parameters

edit
format
(Optional, string) Short version of the HTTP accept header. Valid values include JSON, YAML, etc.
h
(Optional, string) Comma-separated list of column names to display.
help
(Optional, Boolean) If true, the response includes help information. Defaults to false.
s
(Optional, string) Comma-separated list of column names or column aliases used to sort the response.
time
(Optional, time units) Unit used to display time values.
ts (timestamps)
(Optional, Boolean) If true, returns HH:MM:SS and Unix epoch timestamps. Defaults to true.
v
(Optional, Boolean) If true, the response includes column headings. Defaults to false.

Examples

edit

Example with a timestamp

edit

By default, the cat health API returns HH:MM:SS and Unix epoch timestamps. For example:

resp = client.cat.health(
    v=True,
)
print(resp)
response = client.cat.health(
  v: true
)
puts response
const response = await client.cat.health({
  v: "true",
});
console.log(response);
GET /_cat/health?v=true

The API returns the following response:

epoch      timestamp cluster       status node.total node.data shards pri relo init unassign unassign.pri pending_tasks max_task_wait_time active_shards_percent
1475871424 16:17:04  elasticsearch green           1         1      1   1    0    0        0            0             0                  -                100.0%

Example without a timestamp

edit

You can use the ts (timestamps) parameter to disable timestamps. For example:

resp = client.cat.health(
    v=True,
    ts=False,
)
print(resp)
response = client.cat.health(
  v: true,
  ts: false
)
puts response
const response = await client.cat.health({
  v: "true",
  ts: "false",
});
console.log(response);
GET /_cat/health?v=true&ts=false

The API returns the following response:

cluster       status node.total node.data shards pri relo init unassign unassign.pri pending_tasks max_task_wait_time active_shards_percent
elasticsearch green           1         1      1   1    0    0        0            0             0                  -                100.0%

Note: The reported number of unassigned primary shards may be lower than the true value if your cluster contains nodes running a version below 8.16. For a more accurate count in this scenario, please use the cluster health API.

Example across nodes

edit

You can use the cat health API to verify the health of a cluster across nodes. For example:

% pssh -i -h list.of.cluster.hosts curl -s localhost:9200/_cat/health
[1] 20:20:52 [SUCCESS] es3.vm
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0 0
[2] 20:20:52 [SUCCESS] es1.vm
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0 0
[3] 20:20:52 [SUCCESS] es2.vm
1384309218 18:20:18 foo green 3 3 3 3 0 0 0 0 0

Example with a large cluster

edit

You can use the cat health API to track the recovery of a large cluster over a longer period of time. You can do this by including the cat health API request in a delayed loop. For example:

% while true; do curl localhost:9200/_cat/health; sleep 120; done
1384309446 18:24:06 foo red 3 3 20 20 0 0 1812 1121 0
1384309566 18:26:06 foo yellow 3 3 950 916 0 12 870 421 0
1384309686 18:28:06 foo yellow 3 3 1328 916 0 12 492 301 0
1384309806 18:30:06 foo green 3 3 1832 916 4 0 0 0
^C

In this example, the recovery took roughly six minutes, from 18:24:06 to 18:30:06. If this recovery took hours, you could continue to monitor the number of UNASSIGNED shards, which should drop. If the number of UNASSIGNED shards remains static, it would indicate an issue with the cluster recovery.

« cat fielddata API cat indices API »