Get shard recovery information

GET /_cat/recovery/{index}
GET /_cat/recovery

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

Path Parameters

index union IndexName | [] IndexName optional

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.

Leave it out to use /_cat/recovery.

Query 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

Response 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.

Examples

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.

Request Console 1 / 7 languages

Console Kibana Dev Tools

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

JavaScript Elasticsearch JavaScript Client

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

Python Elasticsearch Python Client

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

curl Shell

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

Java Elasticsearch Java Client

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

PHP Elasticsearch PHP Client

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

Ruby Elasticsearch Ruby Client

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

Response

[
  {
    "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%"
  }
]

Required authorization

Path Parameters

Query Parameters { active_only , detailed , index , h , s , }

Response

Query Parameters