[[cat-recovery]] === cat recovery Returns information about ongoing and completed index shard recoveries, similar to the <> API. [[cat-recovery-api-request]] ==== {api-request-title} `GET /_cat/recovery/{index}` [[cat-recovery-api-desc]] ==== {api-description-title} The cat recovery API returns information about index shard recoveries, both ongoing and completed. It is a more compact view of the JSON <> API. A recovery event occurs anytime an index shard moves to a different node in the cluster. This can happen during a snapshot recovery, a change in replication level, node failure, or on node startup. This last type is called a local store recovery and is the normal way for shards to be loaded from disk when a node starts up. [[cat-recovery-path-params]] ==== {api-path-parms-title} include::{docdir}/rest-api/common-parms.asciidoc[tag=index] [[cat-recovery-query-params]] ==== {api-query-parms-title} include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes] include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format] include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h] include::{docdir}/rest-api/common-parms.asciidoc[tag=help] include::{docdir}/rest-api/common-parms.asciidoc[tag=local] include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s] include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v] [[cat-recovery-api-example]] ==== {api-examples-title} [[cat-recovery-api-ex-dead]] ===== Example with no ongoing recoveries [source,js] ---------------------------------------------------------------------------- GET _cat/recovery?v ---------------------------------------------------------------------------- // CONSOLE // TEST[setup:twitter] The API returns the following response: [source,txt] --------------------------------------------------------------------------- index shard time type stage source_host source_node target_host target_node repository snapshot files files_recovered files_percent files_total bytes bytes_recovered bytes_percent bytes_total translog_ops translog_ops_recovered translog_ops_percent twitter 0 13ms store done n/a n/a 127.0.0.1 node-0 n/a n/a 0 0 100% 13 0 0 100% 9928 0 0 100.0% --------------------------------------------------------------------------- // TESTRESPONSE[s/store/empty_store/] // TESTRESPONSE[s/100%/0.0%/] // TESTRESPONSE[s/9928/0/] // TESTRESPONSE[s/13ms/[0-9.]+m?s/] // TESTRESPONSE[s/13/\\d+/ non_json] In this example response, the source and target nodes are the same because the recovery type is `store`, meaning they were read from local storage on node start. [[cat-recovery-api-ex-live]] ===== Example with a live shard recovery By increasing the replica count of an index and bringing another node online to host the replicas, you can retrieve information about an ongoing recovery. [source,js] ---------------------------------------------------------------------------- GET _cat/recovery?v&h=i,s,t,ty,st,shost,thost,f,fp,b,bp ---------------------------------------------------------------------------- // CONSOLE // TEST[setup:twitter] The API returns the following response: [source,txt] ---------------------------------------------------------------------------- i s t ty st shost thost f fp b bp twitter 0 1252ms peer done 192.168.1.1 192.168.1.2 0 100.0% 0 100.0% ---------------------------------------------------------------------------- // TESTRESPONSE[s/peer/empty_store/] // TESTRESPONSE[s/192.168.1.2/127.0.0.1/] // TESTRESPONSE[s/192.168.1.1/n\/a/] // TESTRESPONSE[s/100.0%/0.0%/] // TESTRESPONSE[s/1252ms/[0-9.]+m?s/ non_json] In this example response, the recovery type is `peer`, meaning the shard recovered from another node. The returned files and bytes are real-time measurements. [[cat-recovery-api-ex-snapshot]] ===== Example with a snapshot recovery You can restore backups of an index using the <> API. You can use the cat recovery API retrieve information about a snapshot recovery. [source,js] -------------------------------------------------------------------------------- GET _cat/recovery?v&h=i,s,t,ty,st,rep,snap,f,fp,b,bp -------------------------------------------------------------------------------- // CONSOLE // TEST[skip:no need to execute snapshot/restore here] The API returns the following response with a recovery type of `snapshot`: [source,txt] -------------------------------------------------------------------------------- i s t ty st rep snap f fp b bp twitter 0 1978ms snapshot done twitter snap_1 79 8.0% 12086 9.0% -------------------------------------------------------------------------------- // TESTRESPONSE[non_json]