Get shard recovery information

  • GET /_cat/recovery/{index}
  • GET /_cat/recovery
Auth

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 string | string[] 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 shard recoveries that have not yet completed (excludes done stage).

detailed boolean · default: false

If true, the response includes detailed information about shard recoveries.

index union string | string[]

Comma-separated list or wildcard expression of index names to limit the returned information

h union oneOf · 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.
  • 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
s union string | 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.

format string · default: text

Specifies the format to return the columnar data in, can be set to text, json, cbor, yaml, or smile.

help boolean · default: false

When set to true will output available columns. This option can't be combined with any other query string option.

v boolean · default: false

When set to true will enable verbose output.

bytes enum

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

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

The index name.

shard string

The shard name.

start_time union oneOf

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

One of: string or number
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 oneOf

The recovery stop time. For recoveries that have not yet completed, this value is the Unix epoch (1970-01-01T00:00:00.000Z).

One of: string or number
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.