Get index recovery information

  • GET /{index}/_recovery
  • GET /_recovery
Auth

Get information about ongoing and completed shard recoveries for one or more indices. For data streams, the API returns information for the stream's backing indices.

All recoveries, whether ongoing or complete, are kept in the cluster state and may be reported on at any time.

Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or creating a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing.

Recovery automatically occurs during the following processes:

  • When creating an index for the first time.
  • When a node rejoins the cluster and starts up any missing primary shard copies using the data that it holds in its data path.
  • Creation of new replica shard copies from the primary.
  • Relocation of a shard copy to a different node in the same cluster.
  • A snapshot restore operation.
  • A clone, shrink, or split operation.

You can determine the cause of a shard recovery using the recovery or cat recovery APIs.

The index recovery API reports information about completed recoveries only for shard copies that currently exist in the cluster. It only reports the last recovery for each shard copy and does not report historical information about earlier recoveries, nor does it report information about the recoveries of shard copies that no longer exist. This means that if a shard copy completes a recovery and then Elasticsearch relocates it onto a different node then the information about the original recovery will not be shown in the recovery API.

Required authorization

Index privileges monitor

Path parameters

index union string | string[] optional

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 /_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.

allow_no_indices boolean · default: true

A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

expand_wildcards union oneOf · default: open

Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:

  • all: Match any data stream or index, including hidden ones.
  • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
  • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
  • none: Wildcard expressions are not accepted.
Values: all open closed hidden none
ignore_unavailable boolean · default: false

If false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

Response

application/json
<string> object
shards object[] required
id number required
index object required
bytes object
percent number | string required
recovered number | string
recovered_in_bytes number | string required
recovered_from_snapshot number | string
recovered_from_snapshot_in_bytes number | string
reused number | string
reused_in_bytes number | string required
total number | string
total_in_bytes number | string required
files object required
details object[]
length number required
name string required
recovered number required
percent number | string required
recovered number required
reused number required
total number required
size object required
percent number | string required
recovered number | string
recovered_in_bytes number | string required
recovered_from_snapshot number | string
recovered_from_snapshot_in_bytes number | string
reused number | string
reused_in_bytes number | string required
total number | string
total_in_bytes number | string required
source_throttle_time string
source_throttle_time_in_millis number required
target_throttle_time string
target_throttle_time_in_millis number required
total_time string
total_time_in_millis number required
primary boolean required
source object required
hostname string
host string
transport_address string
id string
ip string
name string
bootstrap_new_history_uuid boolean
repository string
snapshot string
version string
restoreUUID string
index string
stage enum required

The recovery stage.

Supported values include:

  • CREATED: The shard's recovery state has been created, but the recovery has not started yet (it may be queued behind other ongoing recoveries).
  • INIT: Recovery has started and is initializing.
  • INDEX: Reading index metadata and copying bytes from source to destination.
  • VERIFY_INDEX: Verifying the integrity of the index.
  • TRANSLOG: Replaying the transaction log.
  • FINALIZE: Cleanup.
  • DONE: Complete.
Values: CREATED INIT INDEX VERIFY_INDEX TRANSLOG FINALIZE DONE
local_retries number

The number of times this recovery has failed in a way which is retried locally (i.e. on the data node).

priority enum

The recovery priority.

Supported values include:

  • UNASSIGNED_NEW_PRIMARY: A primary shard which is unassigned because it is newly created.
  • UNASSIGNED_UNEXPECTED: A shard which is unassigned because of an unexpected condition, i.e. some kind of failure.
  • UNASSIGNED_EXPECTED: A shard which is unassigned for an expected condition, i.e. because of a user operation such as opening or restoring an index, but which is not an UNASSIGNED_NEW_PRIMARY.
  • RELOCATION_CAN_REMAIN_NO: A shard which is assigned, and is being relocated because it cannot remain on its current node according to the allocation deciders.
  • RELOCATION_CAN_REMAIN_NOT_PREFERRED: A shard which is assigned, and is being relocated because it is not preferred for it to remain on its current node according to the allocation deciders.
  • RELOCATE_REBALANCING: A shard which is assigned, and is being relocated for rebalancing.
  • UNKNOWN: Placeholder value for unknown priorities.
Values: UNASSIGNED_NEW_PRIMARY UNASSIGNED_UNEXPECTED UNASSIGNED_EXPECTED RELOCATION_CAN_REMAIN_NO RELOCATION_CAN_REMAIN_NOT_PREFERRED RELOCATE_REBALANCING UNKNOWN
gate string

The name of the recovery gate that blocked recovery on the target node.

Only present for queued recoveries in the CREATED stage that are blocked by a recovery gate.

blocked_for_millis number

The elapsed time in milliseconds recovery is blocked for.

Only present with gate.

start object
check_index_time string
check_index_time_in_millis number required
total_time string
total_time_in_millis number required
start_time union oneOf

The time the recovery started. 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_in_millis number required

The time the recovery started, in milliseconds since the Unix epoch. For recoveries in the CREATED stage (not yet started), this value is 0.

stop_time union oneOf

The time the recovery completed. Only present for completed recoveries (DONE stage).

One of: string or number
stop_time_in_millis number

The time the recovery completed, in milliseconds since the Unix epoch. Only present for completed recoveries (DONE stage).

target object required
Same fields as source in shards
total_time string
total_time_in_millis number required

The total elapsed recovery time in milliseconds. For recoveries in the CREATED stage (not yet started), this value is 0.

translog object required
percent number | string required
recovered number required
total number required
total_on_start number required
total_time string
total_time_in_millis number required
type enum required

The recovery source type.

Supported values include:

  • EMPTY_STORE: An empty store. Indicates a new primary shard or the forced allocation of an empty primary shard using the cluster reroute API.
  • EXISTING_STORE: The store of an existing primary shard. Indicates recovery is related to node startup or the allocation of an existing primary shard.
  • LOCAL_SHARDS: Shards of another index on the same node. Indicates recovery is related to a clone, shrink, or split operation.
  • PEER: A primary shard on another node. Indicates recovery is related to shard replication.
  • SNAPSHOT: A snapshot. Indicates recovery is related to a snapshot restore operation.
Values: EMPTY_STORE EXISTING_STORE LOCAL_SHARDS PEER SNAPSHOT
verify_index object required
check_index_time string
check_index_time_in_millis number required
total_time string
total_time_in_millis number required