---
type: api
title: Get shard recovery information
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-cat-recovery
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/operation/operation-cat-recovery
products:
  - Elasticsearch
---

# Get shard recovery information


## Paths

- `GET` `/_cat/recovery/{index}`
- `GET` `/_cat/recovery`

#### Path parameters

- `index` (union string | string[]) — optional, leave it out to use `/_cat/recovery`
  A 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`.

## Description

Get information about ongoing and completed shard recoveries.
Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing.
For data streams, the API returns information about the stream’s backing indices.
IMPORTANT: 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 index recovery API.

## Required authorization

- Index privileges: `monitor`
- Cluster privileges: `monitor`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)

## Query string parameters

- `active_only` (boolean · default: false) — optional
  If `true`, the response only includes shard recoveries that have not yet completed (excludes `done` stage).
- `detailed` (boolean · default: false) — optional
  If `true`, the response includes detailed information about shard recoveries.
- `index` (union oneOf) — optional
  Comma-separated list or wildcard expression of index names to limit the returned information
  One of: `string[]` or `string`
- `h` (union · default: ip,hp,rp,r,m,n,cpu,l) — optional
  A comma-separated list of columns names to display.
It supports simple wildcards.

Supported values include:
  - `index` (or `i`, `idx`): The index name.
  - `shard` (or `s`, `sh`): The shard name.
  - `start_time` (or `start`): The recovery start time.
  - `start_time_millis` (or `start_millis`): The recovery start time in epoch milliseconds.
  - `stop_time` (or `stop`): The recovery stop time.
  - `stop_time_millis` (or `stop_millis`): The recovery stop time in epoch milliseconds.
  - `time` (or `t`, `ti`): The recovery time.
  - `type` (or `ty`): The recovery type.
  - `stage` (or `st`): The recovery stage.
  - `local_retries` (or `lr`): The number of times this recovery has failed in a way which is retried locally (i.e. on the data node).
  - `priority` (or `pr`): The recovery priority.
  - `gate` (or `g`): The name of the recovery gate that blocked recovery on the target node.

The value is `n/a` unless the recovery is queued in the `created` stage and blocked by a recovery gate.
  - `blocked_for_millis` (or `bf`): The elapsed time in milliseconds recovery is blocked for.

The value is `n/a` when the recovery is not blocked by a recovery gate.
  - `source_host` (or `shost`): The source host.
  - `source_node` (or `snode`): The source node name.
  - `target_host` (or `thost`): The target host.
  - `target_node` (or `tnode`): The target node name.
  - `repository` (or `rep`): The repository.
  - `snapshot` (or `snap`): The snapshot.
  - `files` (or `f`): The number of files to recover.
  - `files_recovered` (or `fr`): The files recovered.
  - `files_percent` (or `fp`): The percent of files recovered.
  - `files_total` (or `tf`): The total number of files.
  - `bytes` (or `b`): The number of bytes to recover.
  - `bytes_recovered` (or `br`): The bytes recovered.
  - `bytes_percent` (or `bp`): The percent of bytes recovered.
  - `bytes_total` (or `tb`): The total number of bytes.
  - `translog_ops` (or `to`): The number of translog ops to recover.
  - `translog_ops_recovered` (or `tor`): The translog ops recovered.
  - `translog_ops_percent` (or `top`): The percent of translog ops recovered.
  Values: `index`, `i`, `idx`, `shard`, `s`, `sh`, `start_time`, `start`, `start_time_millis`, `start_millis`, `stop_time`, `stop`, `stop_time_millis`, `stop_millis`, `time`, `t`, `ti`, `type`, `ty`, `stage`, `st`, `local_retries`, `lr`, `priority`, `pr`, `gate`, `g`, `blocked_for_millis`, `bf`, `source_host`, `shost`, `source_node`, `snode`, `target_host`, `thost`, `target_node`, `tnode`, `repository`, `rep`, `snapshot`, `snap`, `files`, `f`, `files_recovered`, `fr`, `files_percent`, `fp`, `files_total`, `tf`, `bytes`, `b`, `bytes_recovered`, `br`, `bytes_percent`, `bp`, `bytes_total`, `tb`, `translog_ops`, `to`, `translog_ops_recovered`, `tor`, `translog_ops_percent`, `top`
- `s` (union oneOf) — optional
  A comma-separated list of column names or aliases that determines the sort order.
Sorting defaults to ascending and can be changed by setting `:asc`
or `:desc` as a suffix to the column name.
  One of: `string[]` or `string`
- `format` (string · default: text) — optional
  Specifies the format to return the columnar data in, can be set to
`text`, `json`, `cbor`, `yaml`, or `smile`.
- `help` (boolean · default: false) — optional
  When set to `true` will output available columns. This option
can't be combined with any other query string option.
- `v` (boolean · default: false) — optional
  When set to `true` will enable verbose output.
- `bytes` (enum) — optional
  Sets the units for columns that contain a byte-size value.
Note that byte-size value units work in terms of powers of 1024. For instance `1kb` means 1024 bytes, not 1000 bytes.
If omitted, byte-size values are rendered with a suffix such as `kb`, `mb`, or `gb`, chosen such that the numeric value of the column is as small as possible whilst still being at least `1.0`.
If given, byte-size values are rendered as an integer with no suffix, representing the value of the column in the chosen unit.
Values that are not an exact multiple of the chosen unit are rounded down.
  Values: `b`, `kb`, `mb`, `gb`, `tb`, `pb`
- `time` (enum) — optional
  Sets the units for columns that contain a time duration.
If omitted, time duration values are rendered with a suffix such as `ms`, `s`, `m` or `h`, chosen such that the numeric value of the column is as small as possible whilst still being at least `1.0`.
If given, time duration values are rendered as an integer with no suffix.
Values that are not an exact multiple of the chosen unit are rounded down.
  Values: `nanos`, `micros`, `ms`, `s`, `m`, `h`, `d`

## Response

`application/json`

Type: `object[]`

An array; each item has these fields:

- `index` (string)
  The index name.
- `shard` (string)
  The shard name.
- `start_time` (union)
  The recovery start time.
For recoveries in the `created` stage (not yet started), this value is the Unix epoch (1970-01-01T00:00:00.000Z).
- `start_time_millis` (number)
  The recovery start time in epoch milliseconds.
For recoveries in the `created` stage (not yet started), this value is 0.
- `stop_time` (union)
  The recovery stop time.
For recoveries that have not yet completed, this value is the Unix epoch (1970-01-01T00:00:00.000Z).
- `stop_time_millis` (number)
  The recovery stop time in epoch milliseconds.
For recoveries that have not yet completed, this value is 0.
- `time` (string)
  The recovery time.
For recoveries in the `created` stage (not yet started), this value is 0.
- `type` (string)
  The recovery type.
- `stage` (string)
  The recovery stage.
- `local_retries` (string)
  The number of times this recovery has failed in a way which is retried locally (i.e. on the data node).
- `priority` (string)
  The recovery priority.
- `gate` (string)
  The name of the recovery gate that blocked recovery on the target node.

The value is `n/a` unless the recovery is queued in the `created` stage and blocked by a recovery gate.
- `blocked_for_millis` (string)
  The elapsed time in milliseconds recovery is blocked for.

The value is `n/a` when the recovery is not blocked by a recovery gate.
- `source_host` (string)
  The source host.
- `source_node` (string)
  The source node name.
- `target_host` (string)
  The target host.
- `target_node` (string)
  The target node name.
- `repository` (string)
  The repository name.
- `snapshot` (string)
  The snapshot name.
- `files` (string)
  The number of files to recover.
- `files_recovered` (string)
  The files recovered.
- `files_percent` (number | string)
  The ratio of files recovered.
- `files_total` (string)
  The total number of files.
- `bytes` (string)
  The number of bytes to recover.
- `bytes_recovered` (string)
  The bytes recovered.
- `bytes_percent` (number | string)
  The ratio of bytes recovered.
- `bytes_total` (string)
  The total number of bytes.
- `translog_ops` (string)
  The number of translog operations to recover.
- `translog_ops_recovered` (string)
  The translog operations recovered.
- `translog_ops_percent` (number | string)
  The ratio of translog operations recovered.
## Code examples

#### Console

```console
GET _cat/recovery?v=true&format=json
```

#### JavaScript

```javascript
const response = await client.cat.recovery({
  v: "true",
  format: "json",
});
```

#### Python

```python
resp = client.cat.recovery(
    v=True,
    format="json",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/_cat/recovery?v=true&format=json" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.cat().recovery(r -> r);
```

#### PHP

```php
$resp = $client->cat()->recovery([
    "v" => "true",
    "format" => "json",
]);
```

#### Ruby

```ruby
response = client.cat.recovery(
  v: "true",
  format: "json"
)
```

## Response examples

#### No ongoing recoveries

A successful response from `GET _cat/recovery?v=true&format=json`. In this example, the source and target nodes are the same because the recovery type is `store`, meaning they were read from local storage on node start.

```json
[
  {
    "index": "my-index-000001 ",
    "shard": "0",
    "time": "13ms",
    "type": "store",
    "stage": "done",
    "source_host": "n/a",
    "source_node": "n/a",
    "target_host": "127.0.0.1",
    "target_node": "node-0",
    "repository": "n/a",
    "snapshot": "n/a",
    "files": "0",
    "files_recovered": "0",
    "files_percent": "100.0%",
    "files_total": "13",
    "bytes": "0b",
    "bytes_recovered": "0b",
    "bytes_percent": "100.0%",
    "bytes_total": "9928b",
    "translog_ops": "0",
    "translog_ops_recovered": "0",
    "translog_ops_percent": "100.0%"
  }
]
```

#### A live shard recovery

A successful response from `GET _cat/recovery?v=true&h=i,s,t,ty,st,shost,thost,f,fp,b,bp&format=json`. You can retrieve information about an ongoing recovery for example when you increase the replica count of an index and bring another node online to host the replicas. In this example, the recovery type is `peer`, meaning the shard recovered from another node. The `files` and `bytes` are real-time measurements.

```json
[
  {
    "i": "my-index-000001",
    "s": "0",
    "t": "1252ms",
    "ty": "peer",
    "st": "done",
    "shost": "192.168.1.1",
    "thost": "192.168.1.1",
    "f": "0",
    "fp": "100.0%",
    "b": "0b",
    "bp": "100.0%",
  }
]
```

#### A snapshot recovery

A successful response from `GET _cat/recovery?v=true&h=i,s,t,ty,st,rep,snap,f,fp,b,bp&format=json`. You can restore backups of an index using the snapshot and restore API. You can use the cat recovery API to get information about a snapshot recovery.

```json
[
  {
    "i": "my-index-000001",
    "s": "0",
    "t": "1978ms",
    "ty": "snapshot",
    "st": "done",
    "rep": "my-repo",
    "snap": "snap-1",
    "f": "79",
    "fp": "8.0%",
    "b": "12086",
    "bp": "9.0%"
  }
]
```