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

# Get shard recovery information


Availability:

## Paths

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

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

#### Path Parameters

- `index` (union IndexName | [] IndexName) — 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`

## Query String Parameters

- `active_only` (boolean · default: false)
  If `true`, the response only includes ongoing shard recoveries.
- `detailed` (boolean · default: false)
  If `true`, the response includes detailed information about shard recoveries.
- `index` (union Indices)
  Comma-separated list or wildcard expression of index names to limit the returned information
  One of: `IndexName` or `IndexName[]`
- `h` (CatRecoveryColumns · default: ip,hp,rp,r,m,n,cpu,l)
  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.
  - `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`, `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 Names)
  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: `Name` or `Name[]`

## Response

`application/json`

Type: `[] RecoveryRecord`

- `index` (string IndexName)
  The index name.
- `shard` (string)
  The shard name.
- `start_time` (DateTime)
  The recovery start time.
- `start_time_millis` (EpochTimeUnitMillis)
  The recovery start time in epoch milliseconds.
- `stop_time` (DateTime)
  The recovery stop time.
- `stop_time_millis` (EpochTimeUnitMillis)
  The recovery stop time in epoch milliseconds.
- `time` (string Duration)
  The recovery time.
- `type` (string)
  The recovery type.
- `stage` (string)
  The recovery stage.
- `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 Percentage)
  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 Percentage)
  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 Percentage)
  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%"
  }
]
```