elasticsearch/docs/reference/search/count.asciidoc

[[search-count]]
=== Count API
++++
<titleabbrev>Count</titleabbrev>
++++

Gets the number of matches for a search query.

[source,console]
--------------------------------------------------
GET /my-index-000001/_count?q=user:kimchy
--------------------------------------------------
// TEST[setup:my_index]

NOTE: The query being sent in the body must be nested in a `query` key, same as
the <<search-search,search API>> works.


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

`GET /<target>/_count`

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

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


[[search-count-api-desc]]
==== {api-description-title}

The count API allows you to execute a query and get the number of matches for
that query. The query can either
be provided using a simple query string as a parameter, or using the
<<query-dsl,Query DSL>> defined within the request body.

The count API supports <<api-multi-index,multi-target syntax>>. You can run a single
count API search across multiple data streams and indices.

The operation is broadcast across all shards. For each shard id group, a replica
is chosen and executed against it. This means that replicas increase the
scalability of count.


[[search-count-api-path-params]]
==== {api-path-parms-title}

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

[[search-count-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

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

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

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

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

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

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

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

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

`min_score`::
(Optional, float)
  Sets the minimum `_score` value that documents must have to be included in the
  result.

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

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

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

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


[[search-count-request-body]]
==== {api-request-body-title}

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


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

[source,console]
--------------------------------------------------
PUT /my-index-000001/_doc/1?refresh
{
  "user.id": "kimchy"
}

GET /my-index-000001/_count?q=user:kimchy

GET /my-index-000001/_count
{
  "query" : {
    "term" : { "user.id" : "kimchy" }
  }
}
--------------------------------------------------

Both examples above do the same: count the number of documents in
`my-index-000001` with a `user.id` of `kimchy`. The API returns the following response:

[source,console-result]
--------------------------------------------------
{
  "count": 1,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}
--------------------------------------------------

The query is optional, and when not provided, it will use `match_all` to
count all the docs.