OpenSearch/docs/reference/cat/health.asciidoc

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

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


[[cat-health-api-request]]
==== {api-request-title}

`GET /_cat/health`


[[cat-health-api-desc]]
==== {api-description-title}

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

[[timestamp]]
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.
* https://en.wikipedia.org/wiki/Unix_time[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 <<cat-health-api-example-across-nodes>>.

You also can use the API to track the recovery of a large cluster
over a longer period of time. See <<cat-health-api-example-large-cluster>>.


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

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

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=time]

`ts` (timestamps)::
(Optional, boolean) If `true`, returns `HH:MM:SS` and
https://en.wikipedia.org/wiki/Unix_time[Unix `epoch`] timestamps. Defaults to
`true`.

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


[[cat-health-api-example]]
==== {api-examples-title}

[[cat-health-api-example-timestamp]]
===== Example with a timestamp
By default, the cat health API returns `HH:MM:SS` and
https://en.wikipedia.org/wiki/Unix_time[Unix `epoch`] timestamps. For example:

[source,console]
--------------------------------------------------
GET /_cat/health?v
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n{"settings":{"number_of_replicas": 0}}\n/]

The API returns the following response:

[source,txt]
--------------------------------------------------
epoch      timestamp cluster       status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1475871424 16:17:04  elasticsearch green           1         1      1   1    0    0        0             0                  -                100.0%
--------------------------------------------------
// TESTRESPONSE[s/1475871424 16:17:04/\\d+ \\d+:\\d+:\\d+/]
// TESTRESPONSE[s/elasticsearch/[^ ]+/ s/0                  -/\\d+ (-|\\d+(\\.\\d+)?[ms]+)/ non_json]

[[cat-health-api-example-no-timestamp]]
===== Example without a timestamp
You can use the `ts` (timestamps) parameter to disable timestamps. For example:

[source,console]
--------------------------------------------------
GET /_cat/health?v&ts=false
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n{"settings":{"number_of_replicas": 0}}\n/]

The API returns the following response:

[source,txt]
--------------------------------------------------
cluster       status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
elasticsearch green           1         1      1   1    0    0        0             0                  -                100.0%
--------------------------------------------------
// TESTRESPONSE[s/elasticsearch/[^ ]+/ s/0                  -/\\d+ (-|\\d+(\\.\\d+)?[ms]+)/ non_json]

[[cat-health-api-example-across-nodes]]
===== Example across nodes
You can use the cat health API to verify the health of a cluster across nodes.
For example:

[source,sh]
--------------------------------------------------
% 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
[2] 20:20:52 [SUCCESS] es1.vm
1384309218 18:20:18 foo green 3 3 3 3 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
--------------------------------------------------
// NOTCONSOLE

[[cat-health-api-example-large-cluster]]
===== Example with a large cluster
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:

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

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.