elasticsearch/docs/reference/cat/snapshots.asciidoc

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

[IMPORTANT]
====
cat APIs are only intended for human consumption using the command line or {kib} 
console. They are _not_ intended for use by applications. For application 
consumption, use the <<get-snapshot-api,get snapshot API>>.
====

Returns information about the <<snapshot-restore,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>`

`GET /_cat/snapshots`

[[cat-snapshots-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`monitor_snapshot`, `create_snapshot`, or `manage`
<<privileges-list-cluster,cluster privilege>> to use this API.


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

`<repository>`::
+
--
(Optional, string) Comma-separated list of snapshot repositories used to limit
the request. Accepts wildcard expressions. `_all` returns all repositories.

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


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

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

include::{es-repo-dir}/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) {wikipedia}/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) {wikipedia}/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::{es-repo-dir}/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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

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

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

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


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

[source,console]
--------------------------------------------------
GET /_cat/snapshots/repo1?v=true&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     repository status start_epoch start_time end_epoch  end_time duration indices successful_shards failed_shards total_shards
snap1  repo1      FAILED 1445616705  18:11:45   1445616978 18:16:18     4.6m       1                 4             1            5
snap2  repo1      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]