<commit_before>[[cat-snapshots]]
=== cat snapshots

The `snapshots` command shows all snapshots that belong to a specific repository
or multiple repositories.
To find a list of available repositories to query, the command `/_cat/repositories` can be used.
Querying the snapshots of a repository named `repo1` then looks as follows.

[source,js]
--------------------------------------------------
GET /_cat/snapshots/repo1?v&s=id
--------------------------------------------------
// CONSOLE
// 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/]

Which looks like:

[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]

Each snapshot contains information about when it was started and stopped.
Start and stop timestamps are available in two formats.
The `HH:MM:SS` output is simply for quick human consumption.
The epoch time retains more information, including date, and is machine sortable if the snapshot process spans days.

It is also possible to get the list of snapshots from multiple repositories.
Here are some examples:

[source,js]
--------------------------------------------------
GET /_cat/snapshots/_all
GET /_cat/snapshots/repo1,repo2
GET /_cat/snapshots/repo*
--------------------------------------------------
// CONSOLE
// TEST[skip:no repo2]

Please note that if one of the repositories fails during the request you will get an exception instead of the table.<commit_msg>[DOCS] Reformats cat snapshots API (#45402)<commit_after>[[cat-snapshots]]
=== cat snapshots

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}`::
+
--
(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::{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]

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

`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=cat-v]


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

[source,js]
--------------------------------------------------
GET /_cat/snapshots/repo1?v&s=id
--------------------------------------------------
// CONSOLE
// 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]


{'fraction_non_alphanumeric': 0.21015138023152272, 'fraction_numerical': 0.03250222617987533, 'mean_word_length': 2.447058823529412, 'pattern_counts': {'":': 6, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5612792', 'n_tokens_mistral': 2241, 'n_tokens_neox': 2111, 'n_words': 606}