elasticsearch/docs/reference/cat/count.asciidoc

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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-cat[Compact and aligned text (CAT) APIs]..
--

[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 <<search-count,count API>>.
====

Provides quick access to a document count for a data stream, an index, or an
entire cluster.

NOTE: The document count only includes live documents, not deleted documents
which have not yet been removed by the merge process.


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

`GET /_cat/count/<target>`

`GET /_cat/count`

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

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for any data stream, index, or alias
you retrieve.

[[cat-count-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-count-api-query-params]]
==== {api-query-parms-title}

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

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

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

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

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


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

[[cat-count-api-example-ind]]
===== Example with an individual data stream or index

The following `count` API request retrieves the document count for the 
`my-index-000001` data stream or index.

[source,console,id=cat-count-individual-example]
--------------------------------------------------
GET /_cat/count/my-index-000001?v=true
--------------------------------------------------
// TEST[setup:my_index_big]


The API returns the following response:

[source,txt]
--------------------------------------------------
epoch      timestamp count
1475868259 15:24:20  120
--------------------------------------------------
// TESTRESPONSE[s/1475868259 15:24:20/\\d+ \\d+:\\d+:\\d+/ non_json]

[[cat-count-api-example-all]]
===== Example with all data streams and indices in a cluster

The following `count` API request retrieves the document count for all data
streams and indices in the cluster.

[source,console,id=cat-count-all-example]
--------------------------------------------------
GET /_cat/count?v=true
--------------------------------------------------
// TEST[setup:my_index_big]
// TEST[s/^/POST test\/_doc\?refresh\n{"test": "test"}\n/]

The API returns the following response:

[source,txt]
--------------------------------------------------
epoch      timestamp count
1475868259 15:24:20  121
--------------------------------------------------
// TESTRESPONSE[s/1475868259 15:24:20/\\d+ \\d+:\\d+:\\d+/ non_json]