Get shard recovery information Generally available

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

Query parameters

  • active_only boolean

    If true, the response only includes ongoing shard recoveries.

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

    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.

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 EpochTimeUnitMillis number

      Time unit for milliseconds

    • start_time_millis number

      Time unit for milliseconds

    • stop_time string | number

      The recovery stop time.

      One of:
      string-1 string EpochTimeUnitMillis number

      Time unit for milliseconds

    • stop_time_millis number

      Time unit for milliseconds

    • time string

      The recovery time.

      External documentation
    • 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
    • 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
    • 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
GET /_cat/recovery 
curl \
 --request GET 'http://api.example.com/_cat/recovery'
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%"
  }
]