OpenSearch/docs/reference/cat/snapshots.asciidoc

[[cat-snapshots]]
=== cat snapshots API
++++
<titleabbrev>cat snapshots</titleabbrev>
++++

Returns information about the <<modules-snapshots,snapshots>> stored in one or
more repositories. A snapshot is a backup of an index or running {es} cluster.


[[cat-snapshots-api-request]]
==== {api-request-title}

`GET /_cat/snapshots/<repository>`


[[cat-snapshots-path-params]]
==== {api-path-parms-title}

`<repository>`::
+
--
(Required, string) Snapshot repository used to limit the request.

If the repository fails during the request, {es} returns an error.
--


[[cat-snapshots-query-params]]
==== {api-query-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
--
If you do not specify which columns to include, the API returns the default
columns in the order listed below. If you explicitly specify one or more
columns, it only returns the specified columns.

Valid columns are:

`id`, `snapshot`::
(Default) ID of the snapshot, such as `snap1`.

`repository`, `re`, `repo`::
(Default) Name of the repository, such as `repo1`.

`status`, `s`::
(Default) State of the snapshot process. Returned values are:
+
* `FAILED`: The snapshot process failed.
* `INCOMPATIBLE`: The snapshot process is incompatible with the current cluster
version.
* `IN_PROGRESS`: The snapshot process started but has not completed.
* `PARTIAL`: The snapshot process completed with a partial success.
* `SUCCESS`: The snapshot process completed with a full success.

`start_epoch`, `ste`, `startEpoch`::
(Default) https://en.wikipedia.org/wiki/Unix_time[Unix `epoch` time] at which
the snapshot process started.

`start_time`, `sti`, `startTime`::
(Default) `HH:MM:SS` time at which the snapshot process started.

`end_epoch`, `ete`, `endEpoch`::
(Default) https://en.wikipedia.org/wiki/Unix_time[Unix `epoch` time] at which
the snapshot process ended.

`end_time`, `eti`, `endTime`::
(Default) `HH:MM:SS` time at which the snapshot process ended.

`duration`, `dur`::
(Default) Time it took the snapshot process to complete in <<time-units,time
units>>.

`indices`, `i`::
(Default) Number of indices in the snapshot.

`successful_shards`, `ss`::
(Default) Number of successful shards in the snapshot.

`failed_shards`, `fs`::
(Default) Number of failed shards in the snapshot.

`total_shards`, `ts`::
(Default) Total number of shards in the snapshot.

`reason, `r`::
Reason for any snapshot failures.
--

include::{docdir}/rest-api/common-parms.asciidoc[tag=help]

`ignore_unavailable`::
(Optional, boolean) If `true`, the response does not include information from
unavailable snapshots. Defaults to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{docdir}/rest-api/common-parms.asciidoc[tag=time]

include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]


[[cat-snapshots-api-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
GET /_cat/snapshots/repo1?v&s=id
--------------------------------------------------
// TEST[s/^/PUT \/_snapshot\/repo1\/snap1?wait_for_completion=true\n/]
// TEST[s/^/PUT \/_snapshot\/repo1\/snap2?wait_for_completion=true\n/]
// TEST[s/^/PUT \/_snapshot\/repo1\n{"type": "fs", "settings": {"location": "repo\/1"}}\n/]

The API returns the following response:

[source,txt]
--------------------------------------------------
id     status start_epoch start_time end_epoch  end_time duration indices successful_shards failed_shards total_shards
snap1  FAILED 1445616705  18:11:45   1445616978 18:16:18     4.6m       1                 4             1            5
snap2 SUCCESS 1445634298  23:04:58   1445634672 23:11:12     6.2m       2                10             0           10
--------------------------------------------------
// TESTRESPONSE[s/FAILED/SUCCESS/ s/14456\d+/\\d+/ s/\d+(\.\d+)?(m|s|ms)/\\d+(\\.\\d+)?(m|s|ms)/]
// TESTRESPONSE[s/\d+:\d+:\d+/\\d+:\\d+:\\d+/]
// TESTRESPONSE[s/1                 4             1            5/\\d+ \\d+ \\d+ \\d+/]
// TESTRESPONSE[s/2                10             0           10/\\d+ \\d+ \\d+ \\d+/]
// TESTRESPONSE[non_json]