Get shard recovery information | Elasticsearch API documentation

Get shard recovery information Generally available

GET /_cat/recovery/{index}

All methods and paths for this operation:

GET /_cat/recovery

GET /_cat/recovery/{index}

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 string | array[string] Required

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.

Query parameters

active_only boolean

If true, the response only includes ongoing shard recoveries.
bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
detailed boolean

If true, the response includes detailed information about shard recoveries.
index string | array[string]

Comma-separated list or wildcard expression of index names to limit the returned information
h string | array[string]
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 are 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, or top.
s string | array[string]

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.
time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.

Responses

200 application/json
Hide response attributes Show response attributes object
- index string
  
  The index name.
- shard string
  
  The shard name.
- start_time string | number
  
  The recovery start time.
  
  One of:
  string-1 string UnitMillis number
  
  The recovery start time.
- start_time_millis number
  
  Time unit for milliseconds
- stop_time string | number
  
  The recovery stop time.
  
  One of:
  string-1 string UnitMillis number
  
  The recovery stop time.
- stop_time_millis number
  
  Time unit for milliseconds
- time string
  
  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 string | number
  
  The ratio of files recovered.
  
  One of:
  string-1 string number-2 number
  
  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 string | number
  
  The ratio of bytes recovered.
  
  One of:
  string-1 string number-2 number
  
  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 string | number
  
  The ratio of translog operations recovered.
  
  One of:
  string-1 string number-2 number
  
  The ratio of translog operations recovered.

GET /_cat/recovery/{index}

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

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

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

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

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

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

Response examples (200)

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.

[
  {
    "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 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.

[
  {
    "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 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.

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

Get shard recovery information Generally available

Required authorization

Path parameters

Query parameters

Responses

start_time string | number

stop_time string | number

files_percent string | number

bytes_percent string | number

translog_ops_percent string | number