elasticsearch/docs/reference/cat/recovery.asciidoc

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

[IMPORTANT]
====
cat APIs are only intended for human consumption using the command line or {kib} 
console. They are _not_ intended for use by applications. For application 
consumption, use the <<indices-recovery,index recovery API>>.
====

Returns information about ongoing and completed shard recoveries,
similar to the <<indices-recovery, index recovery>> API.

For data streams, the API returns information about the stream's backing
indices.

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

`GET /_cat/recovery/<target>`

`GET /_cat/recovery`

[[cat-recovery-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API. You must
also have the `monitor` or `manage` <<privileges-list-indices,index privilege>>
for any data stream, index, or alias you retrieve.

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

The cat recovery API returns information about shard recoveries, both
ongoing and completed. It is a more compact view of the JSON
<<indices-recovery,index recovery>> API.

include::{es-repo-dir}/indices/recovery.asciidoc[tag=shard-recovery-desc]


[[cat-recovery-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) Comma-separated list of data streams, indices, and aliases
used to limit the request. Supports wildcards (`*`). To target all data streams
and indices, omit this parameter or use `*` or `_all`.

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

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

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

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

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=index-query-parm]

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

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

include::{es-repo-dir}/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,console]
----------------------------------------------------------------------------
GET _cat/recovery?v=true
----------------------------------------------------------------------------
// TEST[setup:my_index]

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
my-index-000001   0     13ms store done  n/a         n/a         127.0.0.1   node-0      n/a        n/a      0     0               100%          13          0b    0b              100%          9928b       0            0                      100.0%
---------------------------------------------------------------------------
// TESTRESPONSE[s/store/empty_store/]
// TESTRESPONSE[s/100%/0.0%/]
// TESTRESPONSE[s/9928b/0b/]
// 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,console]
----------------------------------------------------------------------------
GET _cat/recovery?v=true&h=i,s,t,ty,st,shost,thost,f,fp,b,bp
----------------------------------------------------------------------------
// TEST[setup:my_index]

The API returns the following response:

[source,txt]
----------------------------------------------------------------------------
i               s t      ty   st    shost       thost       f     fp      b  bp
my-index-000001 0 1252ms peer done  192.168.1.1 192.168.1.2 0     100.0%  0b 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 <<modules-snapshots,snapshot and
restore>> API. You can use the cat recovery API retrieve information about a
snapshot recovery.

[source,console]
--------------------------------------------------------------------------------
GET _cat/recovery?v=true&h=i,s,t,ty,st,rep,snap,f,fp,b,bp
--------------------------------------------------------------------------------
// 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
my-index-000001 0 1978ms snapshot done  my-repo snap-1 79 8.0% 12086 9.0%
--------------------------------------------------------------------------------
// TESTRESPONSE[non_json]