Get snapshot status

Introduced 1.0

Returns details about a snapshot’s state during and after snapshot creation.

To learn about snapshot creation, see Create snapshot.

If you use the Security plugin, you must have the monitor_snapshot, create_snapshot, or manage cluster privileges.

Path and HTTP methods

  1. GET _snapshot/<repository>/<snapshot>/_status

Path parameters

Path parameters are optional.

ParameterData typeDescription
repositoryStringThe repository containing the snapshot.
snapshotListThe snapshot(s) to return.
indexListThe indexes to include in the response.

Three request variants provide flexibility:

  • GET _snapshot/_status returns the status of all currently running snapshots in all repositories.

  • GET _snapshot/<repository>/_status returns all currently running snapshots in the specified repository. This is the preferred variant.

  • GET _snapshot/<repository>/<snapshot>/_status returns detailed status information for a specific snapshot(s) in the specified repository, regardless of whether it’s currently running.

  • GET /_snapshot/<repository>/<snapshot>/<index>/_status returns detailed status information only for the specified indexes in a specific snapshot in the specified repository. Note that this endpoint works only for indexes belonging to a specific snapshot.

Snapshot API calls only work if the total number of shards across the requested resources, such as snapshots and indexes created from snapshots, is smaller than the limit specified by the following cluster setting:

  • snapshot.max_shards_allowed_in_status_api(Dynamic, integer): The maximum number of shards that can be included in the Snapshot Status API response. Default value is 200000. Not applicable for shallow snapshots v2, where the total number and sizes of files are returned as 0.

Using the API to return the state of snapshots that are not currently running can be very costly in terms of both machine resources and processing time when querying data in the cloud. For each snapshot, each request causes a file read of all of the snapshot’s shards.

Request body fields

FieldData typeDescription
ignore_unavailableBooleanHow to handle requests for unavailable snapshots and indexes. If false, the request returns an error for unavailable snapshots and indexes. If true, the request ignores unavailable snapshots and indexes, such as those that are corrupted or temporarily cannot be returned. Default is false.

Example request

The following request returns the status of my-first-snapshot in the my-opensearch-repo repository. Unavailable snapshots are ignored.

  1. GET _snapshot/my-opensearch-repo/my-first-snapshot/_status
  2. {
  3.    "ignore_unavailable": true 
  4. }

copy

Example response

The example that follows corresponds to the request above in the Example request section.

The GET _snapshot/my-opensearch-repo/my-first-snapshot/_status request returns the following fields:

  1. {
  2.   "snapshots" : [
  3.     {
  4.       "snapshot" : "my-first-snapshot",
  5.       "repository" : "my-opensearch-repo",
  6.       "uuid" : "dCK4Qth-TymRQ7Tu7Iga0g",
  7.       "state" : "SUCCESS",
  8.       "include_global_state" : true,
  9.       "shards_stats" : {
  10.         "initializing" : 0,
  11.         "started" : 0,
  12.         "finalizing" : 0,
  13.         "done" : 7,
  14.         "failed" : 0,
  15.         "total" : 7
  16.       },
  17.       "stats" : {
  18.         "incremental" : {
  19.           "file_count" : 31,
  20.           "size_in_bytes" : 24488927
  21.         },
  22.         "total" : {
  23.           "file_count" : 31,
  24.           "size_in_bytes" : 24488927
  25.         },
  26.         "start_time_in_millis" : 1660666841667,
  27.         "time_in_millis" : 14054
  28.       },
  29.       "indices" : {
  30.         ".opensearch-observability" : {
  31.           "shards_stats" : {
  32.             "initializing" : 0,
  33.             "started" : 0,
  34.             "finalizing" : 0,
  35.             "done" : 1,
  36.             "failed" : 0,
  37.             "total" : 1
  38.           },
  39.           "stats" : {
  40.             "incremental" : {
  41.               "file_count" : 1,
  42.               "size_in_bytes" : 208
  43.             },
  44.             "total" : {
  45.               "file_count" : 1,
  46.               "size_in_bytes" : 208
  47.             },
  48.             "start_time_in_millis" : 1660666841868,
  49.             "time_in_millis" : 201
  50.           },
  51.           "shards" : {
  52.             "0" : {
  53.               "stage" : "DONE",
  54.               "stats" : {
  55.                 "incremental" : {
  56.                   "file_count" : 1,
  57.                   "size_in_bytes" : 208
  58.                 },
  59.                 "total" : {
  60.                   "file_count" : 1,
  61.                   "size_in_bytes" : 208
  62.                 },
  63.                 "start_time_in_millis" : 1660666841868,
  64.                 "time_in_millis" : 201
  65.               }
  66.             }
  67.           }
  68.         },
  69.         "shakespeare" : {
  70.           "shards_stats" : {
  71.             "initializing" : 0,
  72.             "started" : 0,
  73.             "finalizing" : 0,
  74.             "done" : 1,
  75.             "failed" : 0,
  76.             "total" : 1
  77.           },
  78.           "stats" : {
  79.             "incremental" : {
  80.               "file_count" : 4,
  81.               "size_in_bytes" : 18310117
  82.             },
  83.             "total" : {
  84.               "file_count" : 4,
  85.               "size_in_bytes" : 18310117
  86.             },
  87.             "start_time_in_millis" : 1660666842470,
  88.             "time_in_millis" : 13050
  89.           },
  90.           "shards" : {
  91.             "0" : {
  92.               "stage" : "DONE",
  93.               "stats" : {
  94.                 "incremental" : {
  95.                   "file_count" : 4,
  96.                   "size_in_bytes" : 18310117
  97.                 },
  98.                 "total" : {
  99.                   "file_count" : 4,
  100.                   "size_in_bytes" : 18310117
  101.                 },
  102.                 "start_time_in_millis" : 1660666842470,
  103.                 "time_in_millis" : 13050
  104.               }
  105.             }
  106.           }
  107.         },
  108.         "opensearch_dashboards_sample_data_flights" : {
  109.           "shards_stats" : {
  110.             "initializing" : 0,
  111.             "started" : 0,
  112.             "finalizing" : 0,
  113.             "done" : 1,
  114.             "failed" : 0,
  115.             "total" : 1
  116.           },
  117.           "stats" : {
  118.             "incremental" : {
  119.               "file_count" : 10,
  120.               "size_in_bytes" : 6132245
  121.             },
  122.             "total" : {
  123.               "file_count" : 10,
  124.               "size_in_bytes" : 6132245
  125.             },
  126.             "start_time_in_millis" : 1660666843476,
  127.             "time_in_millis" : 6221
  128.           },
  129.           "shards" : {
  130.             "0" : {
  131.               "stage" : "DONE",
  132.               "stats" : {
  133.                 "incremental" : {
  134.                   "file_count" : 10,
  135.                   "size_in_bytes" : 6132245
  136.                 },
  137.                 "total" : {
  138.                   "file_count" : 10,
  139.                   "size_in_bytes" : 6132245
  140.                 },
  141.                 "start_time_in_millis" : 1660666843476,
  142.                 "time_in_millis" : 6221
  143.               }
  144.             }
  145.           }
  146.         },
  147.         ".opendistro-reports-definitions" : {
  148.           "shards_stats" : {
  149.             "initializing" : 0,
  150.             "started" : 0,
  151.             "finalizing" : 0,
  152.             "done" : 1,
  153.             "failed" : 0,
  154.             "total" : 1
  155.           },
  156.           "stats" : {
  157.             "incremental" : {
  158.               "file_count" : 1,
  159.               "size_in_bytes" : 208
  160.             },
  161.             "total" : {
  162.               "file_count" : 1,
  163.               "size_in_bytes" : 208
  164.             },
  165.             "start_time_in_millis" : 1660666843076,
  166.             "time_in_millis" : 200
  167.           },
  168.           "shards" : {
  169.             "0" : {
  170.               "stage" : "DONE",
  171.               "stats" : {
  172.                 "incremental" : {
  173.                   "file_count" : 1,
  174.                   "size_in_bytes" : 208
  175.                 },
  176.                 "total" : {
  177.                   "file_count" : 1,
  178.                   "size_in_bytes" : 208
  179.                 },
  180.                 "start_time_in_millis" : 1660666843076,
  181.                 "time_in_millis" : 200
  182.               }
  183.             }
  184.           }
  185.         },
  186.         ".opendistro-reports-instances" : {
  187.           "shards_stats" : {
  188.             "initializing" : 0,
  189.             "started" : 0,
  190.             "finalizing" : 0,
  191.             "done" : 1,
  192.             "failed" : 0,
  193.             "total" : 1
  194.           },
  195.           "stats" : {
  196.             "incremental" : {
  197.               "file_count" : 1,
  198.               "size_in_bytes" : 208
  199.             },
  200.             "total" : {
  201.               "file_count" : 1,
  202.               "size_in_bytes" : 208
  203.             },
  204.             "start_time_in_millis" : 1660666841667,
  205.             "time_in_millis" : 201
  206.           },
  207.           "shards" : {
  208.             "0" : {
  209.               "stage" : "DONE",
  210.               "stats" : {
  211.                 "incremental" : {
  212.                   "file_count" : 1,
  213.                   "size_in_bytes" : 208
  214.                 },
  215.                 "total" : {
  216.                   "file_count" : 1,
  217.                   "size_in_bytes" : 208
  218.                 },
  219.                 "start_time_in_millis" : 1660666841667,
  220.                 "time_in_millis" : 201
  221.               }
  222.             }
  223.           }
  224.         },
  225.         ".kibana_1" : {
  226.           "shards_stats" : {
  227.             "initializing" : 0,
  228.             "started" : 0,
  229.             "finalizing" : 0,
  230.             "done" : 1,
  231.             "failed" : 0,
  232.             "total" : 1
  233.           },
  234.           "stats" : {
  235.             "incremental" : {
  236.               "file_count" : 13,
  237.               "size_in_bytes" : 45733
  238.             },
  239.             "total" : {
  240.               "file_count" : 13,
  241.               "size_in_bytes" : 45733
  242.             },
  243.             "start_time_in_millis" : 1660666842673,
  244.             "time_in_millis" : 2007
  245.           },
  246.           "shards" : {
  247.             "0" : {
  248.               "stage" : "DONE",
  249.               "stats" : {
  250.                 "incremental" : {
  251.                   "file_count" : 13,
  252.                   "size_in_bytes" : 45733
  253.                 },
  254.                 "total" : {
  255.                   "file_count" : 13,
  256.                   "size_in_bytes" : 45733
  257.                 },
  258.                 "start_time_in_millis" : 1660666842673,
  259.                 "time_in_millis" : 2007
  260.               }
  261.             }
  262.           }
  263.         },
  264.         ".opensearch-notifications-config" : {
  265.           "shards_stats" : {
  266.             "initializing" : 0,
  267.             "started" : 0,
  268.             "finalizing" : 0,
  269.             "done" : 1,
  270.             "failed" : 0,
  271.             "total" : 1
  272.           },
  273.           "stats" : {
  274.             "incremental" : {
  275.               "file_count" : 1,
  276.               "size_in_bytes" : 208
  277.             },
  278.             "total" : {
  279.               "file_count" : 1,
  280.               "size_in_bytes" : 208
  281.             },
  282.             "start_time_in_millis" : 1660666842270,
  283.             "time_in_millis" : 200
  284.           },
  285.           "shards" : {
  286.             "0" : {
  287.               "stage" : "DONE",
  288.               "stats" : {
  289.                 "incremental" : {
  290.                   "file_count" : 1,
  291.                   "size_in_bytes" : 208
  292.                 },
  293.                 "total" : {
  294.                   "file_count" : 1,
  295.                   "size_in_bytes" : 208
  296.                 },
  297.                 "start_time_in_millis" : 1660666842270,
  298.                 "time_in_millis" : 200
  299.               }
  300.             }
  301.           }
  302.         }
  303.       }
  304.     }
  305.   ]
  306. }

Response body fields

FieldData typeDescription
repositoryStringName of repository that contains the snapshot.
snapshotStringSnapshot name.
uuidStringA snapshot’s universally unique identifier (UUID).
stateStringSnapshot’s current status. See Snapshot states.
include_global_stateBooleanWhether the current cluster state is included in the snapshot.
shards_statsObjectSnapshot’s shard counts. See Shard stats.
statsObjectInformation about files included in the snapshot. file_count: number of files. size_in_bytes: total size of all files. See Snapshot file stats.
indexlist of ObjectsList of objects that contain information about the indices in the snapshot. See Index objects.

Snapshot states

StateDescription
FAILEDThe snapshot terminated in an error and no data was stored.
IN_PROGRESSThe snapshot is currently running.
PARTIALThe global cluster state was stored, but data from at least one shard was not stored. The failures property of the Create snapshot response contains additional details.
SUCCESSThe snapshot finished and all shards were stored successfully.

Shard stats

All property values are integers.

PropertyDescription
initializingNumber of shards that are still initializing.
startedNumber of shards that have started but not are not finalized.
finalizingNumber of shards that are finalizing but are not done.
doneNumber of shards that initialized, started, and finalized successfully.
failedNumber of shards that failed to be included in the snapshot.
totalTotal number of shards included in the snapshot.

Snapshot file stats

PropertyTypeDescription
incrementalObjectNumber and size of files that still need to be copied during snapshot creation. For completed snapshots, incremental provides the number and size of files that were not already in the repository and were copied as part of the incremental snapshot.
processedObjectNumber and size of files already uploaded to the snapshot. The processed file_count and size_in_bytes are incremented in stats after a file is uploaded.
totalObjectTotal number and size of files that are referenced by the snapshot.
start_time_in_millisLongTime (in milliseconds) when snapshot creation began.
time_in_millisLongTotal time (in milliseconds) that the snapshot took to complete.

Index objects

PropertyTypeDescription
shards_statsObjectSee Shard stats.
statsObjectSee Snapshot file stats.
shardsList of objectsContains information about the shards included in the snapshot. OpenSearch returns the following properties about the shard:

stage: The current state of shards in the snapshot. Shard states are:

DONE: The number of shards in the snapshot that were successfully stored in the repository.

 FAILURE: The number of shards in the snapshot that were not successfully stored in the repository.

FINALIZE: The number of shards in the snapshot that are in the finalizing stage of being stored in the repository.

 INIT: The number of shards in the snapshot that are in the initializing stage of being stored in the repository.

* STARTED: The number of shards in the snapshot that are in the started stage of being stored in the repository.

stats: See Snapshot file stats.

total: The total number and sizes of files referenced by the snapshot.

start_time_in_millis: The time (in milliseconds) when snapshot creation began.

time_in_millis: The total amount of time (in milliseconds) that the snapshot took to complete.