Count API

Introduced 1.0

The Count API returns the count of documents that match a query. You can use it to retrieve the document count of an index, a data stream, or a cluster. Common use cases include:

• Retrieving the total number of documents in an index or data stream without retrieving the actual documents.
• Verifying that data has been indexed correctly by counting documents that match specific criteria.
• Monitoring data growth over time by tracking document counts across different time periods.
• Validating query results before running expensive search operations by first retrieving how many documents match.

The Count API is more efficient than using the Search API with size: 0 when you only need the document count because it is optimized specifically for counting operations. To improve performance, OpenSearch distributes the count query across all shards in parallel. Each shard processes the request using one of its available replicas, allowing horizontal scaling as the number of replicas increases.

Alternatively, you can use the CAT Indices API or the CAT Count API to retrieve the number of documents in each index or data stream.

Endpoints

GET  /_count
POST /_count
GET  /{index}/_count
POST /{index}/_count

Path parameters

The following table lists the available path parameters. All path parameters are optional.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Request body fields

The request body is optional. You can use it to restrict the results using a query defined with Query DSL.

Example: Counting all documents in a cluster

The following example request returns the total count of all documents across the entire cluster:

GET /_count

response = client.count(
  body = { "Insert body here" }
)

Example: Counting all documents in several indexes

The following example request returns the total count of all documents in the movies and tv_shows indexes:

GET /movies,tv_shows/_count

response = client.count(
  index = "movies,tv_shows",
  body = { "Insert body here" }
)

Example: Counting documents that match a query

The following example request counts documents in the movies index in which the genre field is drama:

POST /movies/_count
{
  "query": {
    "term": {
      "genre": "drama"
    }
  }
}

response = client.count(
  index = "movies",
  body =   {
    "query": {
      "term": {
        "genre": "drama"
      }
    }
  }
)

Example: Counting documents using a query string

The following example request uses the q query parameter to count documents where the genre field is drama:

GET /movies/_count?q=genre:drama

response = client.count(
  index = "movies",
  params = { "q": "genre:drama" },
  body = { "Insert body here" }
)

Example: Counting documents with early termination

The following example request uses the terminate_after parameter to stop counting after finding three matching documents:

POST /movies/_count?terminate_after=3
{
  "query": {
    "match_all": {}
  }
}

response = client.count(
  index = "movies",
  params = { "terminate_after": "3" },
  body =   {
    "query": {
      "match_all": {}
    }
  }
)

Example response

The following example response shows the document count and shard information:

{
  "count" : 7,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  }
}

When using the terminate_after parameter, the response includes a terminated_early field:

{
  "terminated_early" : true,
  "count" : 7,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  }
}

Response body fields

The Count API response contains the following fields.