elasticsearch/docs/reference/cat/indices.asciidoc

[[cat-indices]]
=== cat indices API
++++
<titleabbrev>cat indices</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 <<indices-get-index,get index API>>.
====

Returns high-level information about indices in a cluster, including backing
indices for data streams.


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

`GET /_cat/indices/<target>`

`GET /_cat/indices`

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

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API. You must
also have the `monitor` or `manage` <<privileges-list-indices,index privilege>>
for any data stream, index, or alias you retrieve.

[[cat-indices-api-desc]]
==== {api-description-title}

Use the cat indices API to get the following information for each index in a
cluster:

* Shard count
* Document count
* Deleted document count
* Primary store size
* Total store size of all shards, including shard replicas

These metrics are retrieved directly from
https://lucene.apache.org/core/[Lucene], which {es} uses internally to power
indexing and search. As a result, all document counts include hidden
<<nested,nested>> documents.

To get an accurate count of {es} documents, use the <<cat-count,cat count>> or
<<search-count,count>> APIs.


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

`<target>`::
(Optional, string) Comma-separated list of data streams, indices, and aliases
used to limit the request. Supports wildcards (`*`). To target all data streams
and indices, omit this parameter or use `*` or `_all`.

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

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

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

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

`health`::
+
--
(Optional, string) Health status used to limit returned indices. Valid values
are:

* `green`
* `yellow`
* `red`

By default, the response includes indices of any health status.
--

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

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

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

[[pri-flag]]
`pri` (primary shards)::
(Optional, Boolean) If `true`, the response only includes information from
primary shards. Defaults to `false`.

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]

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


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

[[examples]]
[source,console]
--------------------------------------------------
GET /_cat/indices/my-index-*?v=true&s=index
--------------------------------------------------
// TEST[setup:my_index_huge]
// TEST[s/^/PUT my-index-000002\n{"settings": {"number_of_replicas": 0}}\n/]

The API returns the following response:

[source,txt]
--------------------------------------------------
health status index            uuid                   pri rep docs.count docs.deleted store.size pri.store.size
yellow open   my-index-000001  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
green  open   my-index-000002  nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
--------------------------------------------------
// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]