---
type: api
title: Query watches
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-watcher-query-watches
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-watcher-query-watches
products:
  - Elasticsearch
---

# Query watches


Availability: 7.11+

## Paths

- `POST` (also `GET`) `/_watcher/_query/watches`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth)

## Description

Get all registered watches in a paginated manner and optionally filter watches by a query.

Note that only the `_id` and `metadata.*` fields are queryable or sortable.

## Required authorization

* Cluster privileges: `monitor_watcher`

## Request Body

`application/json`

- `from` (number · default: 0) — optional
  The offset from the first result to fetch.
It must be non-negative.
- `size` (number · default: 10) — optional
  The number of hits to return.
It must be non-negative.
- `query` ({} QueryContainer) — optional
  A query that filters the watches to be returned.
  See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/types/_types-query_dsl-querycontainer)
- `sort` (Sort) — optional
  One or more fields used to sort the search results.
- `search_after` (SortResults) — optional
  Retrieve the next page of hits using a set of sort values from the previous page.

## Response

`application/json`

- `count` (number)
  The total number of watches found.
- `watches` ([] QueryWatch)
  A list of watches based on the `from`, `size`, or `search_after` request body parameters.
  - `_id` (string Id)
  - `status` ({} WatchStatus)
    - `actions` (Actions)
    - `last_checked` (DateTime)
    - `last_met_condition` (DateTime)
    - `state` ({} ActivationState)
      - `active` (boolean)
      - `timestamp` (DateTime)
    - `version` (number VersionNumber)
    - `execution_state` (string)
  - `watch` ({} Watch)
    - `actions` (map string to Action)
      Map values ({} Action)
      - `action_type` (enum ActionType)
        Values: `email`, `webhook`, `index`, `logging`, `slack`, `pagerduty`
      - `condition` ({} ConditionContainer)
        - `always` (AlwaysCondition)
        - `array_compare` (map string to ArrayCompareCondition)
          Map values ({} ArrayCompareCondition)
          - `path` (string)
        - `compare` (map string to string to FieldValue)
        - `never` (NeverCondition)
        - `script` ({} ScriptCondition)
          - `lang` (string · default: painless)
          - `params` (map string to object)
          - `source` (string)
          - `id` (string)
      - `foreach` (string)
      - `max_iterations` (number)
      - `name` (string Name)
      - `throttle_period` (string Duration)
      - `throttle_period_in_millis` (DurationValueUnitMillis)
      - `transform` ({} TransformContainer)
        - `chain` ([] TransformContainer) — recursive
          Same fields as `transform` in `actions`
        - `script` ({} ScriptTransform)
          - `lang` (string · default: painless)
          - `params` (map string to object)
          - `source` (string)
          - `id` (string)
        - `search` ({} SearchTransform)
          - `request` ({} SearchInputRequestDefinition)
            - `body` ({} SearchInputRequestBody)
              - `query` ({} QueryContainer)
                See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/types/_types-query_dsl-querycontainer)
            - `indices` ([] string IndexName)
            - `indices_options` ({} IndicesOptions)
              - `allow_no_indices` (boolean)
                If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only
missing or closed indices. This behavior applies even if the request targets other open indices. For example,
a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.
              - `expand_wildcards` (string ExpandWildcards)
                Type of index that wildcard patterns can match. If the request can target data streams, this argument
determines whether wildcard expressions match hidden data streams. Supports comma-separated values,
such as `open,hidden`.

Supported values include:
  - `all`: Match any data stream or index, including hidden ones.
  - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream.
  - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`.
  - `none`: Wildcard expressions are not accepted.
                Values: `all`, `open`, `closed`, `hidden`, `none`
              - `ignore_unavailable` (boolean · default: false)
                If true, missing or closed indices are not included in the response.
              - `ignore_throttled` (boolean · default: true)
                If true, concrete, expanded or aliased indices are ignored when frozen.
            - `search_type` (enum SearchType)
              

Supported values include:
  - `query_then_fetch`: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
  - `dfs_query_then_fetch`: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
              Values: `query_then_fetch`, `dfs_query_then_fetch`
            - `template` ({} SearchTemplateRequestBody)
              - `explain` (boolean · default: false)
              - `id` (string Id)
                ID of the search template to use. If no source is specified,
this parameter is required.
              - `params` (map string to object)
              - `profile` (boolean · default: false)
              - `source` (string)
                An inline search template. Supports the same parameters as the search API's
request body. Also supports Mustache variables. If no id is specified, this
parameter is required.
            - `rest_total_hits_as_int` (boolean)
          - `timeout` (string Duration)
      - `index` ({} IndexAction)
        - `index` (string IndexName)
        - `doc_id` (string Id)
        - `refresh` (enum Refresh)
          Values: `true`, `false`, `wait_for`
        - `op_type` (enum OpType · default: index)
          

Supported values include:
  - `index`: Overwrite any documents that already exist.
  - `create`: Only index documents that do not already exist.
          Values: `index`, `create`
        - `timeout` (string Duration · default: 60s)
        - `execution_time_field` (string Field)
      - `logging` ({} LoggingAction)
        - `level` (string)
        - `text` (string)
        - `category` (string)
      - `email` ({} EmailAction)
        - `id` (string Id)
        - `bcc` (union string | [] string)
        - `body` ({} EmailBody)
          - `html` (string)
          - `text` (string)
        - `cc` (union string | [] string)
        - `from` (string)
        - `priority` (enum EmailPriority)
          Values: `lowest`, `low`, `normal`, `high`, `highest`
        - `reply_to` (union string | [] string)
        - `sent_date` (DateTime)
        - `subject` (string)
        - `to` (union string | [] string)
        - `attachments` (map string to EmailAttachmentContainer)
          Map values ({} EmailAttachmentContainer)
          - `http` ({} HttpEmailAttachment)
            - `content_type` (string)
            - `inline` (boolean)
            - `request` ({} HttpInputRequestDefinition)
              - `auth` ({} HttpInputAuthentication)
                - `basic` ({} HttpInputBasicAuthentication)
                  - `password` (string)
                  - `username` (string)
              - `body` (string)
              - `connection_timeout` (string Duration)
              - `headers` (map string to string)
              - `host` (string)
              - `method` (enum HttpInputMethod)
                Values: `head`, `get`, `post`, `put`, `delete`
              - `params` (map string to string)
              - `path` (string)
              - `port` (number uint)
              - `proxy` ({} HttpInputProxy)
                - `host` (string)
                - `port` (number uint)
              - `read_timeout` (string Duration)
              - `scheme` (enum ConnectionScheme)
                Values: `http`, `https`
              - `url` (string)
          - `reporting` ({} ReportingEmailAttachment)
            - `url` (string)
            - `inline` (boolean)
            - `retries` (number · default: 40)
            - `interval` (string Duration · default: 15s)
            - `request` ({} HttpInputRequestDefinition)
              Same fields as `request` in `http`
          - `data` ({} DataEmailAttachment)
            - `format` (enum DataAttachmentFormat)
              Values: `json`, `yaml`
      - `pagerduty` ({} PagerDutyAction)
        - `account` (string)
        - `attach_payload` (boolean)
        - `client` (string)
        - `client_url` (string)
        - `contexts` ([] PagerDutyContext)
          - `href` (string)
          - `src` (string)
          - `type` (enum PagerDutyContextType)
            Values: `link`, `image`
        - `description` (string)
        - `event_type` (enum PagerDutyEventType · default: trigger)
          Values: `trigger`, `resolve`, `acknowledge`
        - `incident_key` (string)
        - `proxy` ({} PagerDutyEventProxy)
          - `host` (string)
          - `port` (number)
      - `slack` ({} SlackAction)
        - `account` (string)
        - `message` ({} SlackMessage)
          - `attachments` ([] SlackAttachment)
            - `author_icon` (string)
            - `author_link` (string)
            - `author_name` (string)
            - `color` (string)
            - `fallback` (string)
            - `fields` ([] SlackAttachmentField)
              - `short` (boolean)
              - `title` (string)
              - `value` (string)
            - `footer` (string)
            - `footer_icon` (string)
            - `image_url` (string)
            - `pretext` (string)
            - `text` (string)
            - `thumb_url` (string)
            - `title` (string)
            - `title_link` (string)
            - `ts` (EpochTimeUnitSeconds)
          - `dynamic_attachments` ({} SlackDynamicAttachment)
            - `attachment_template` ({} SlackAttachment)
              Same fields as `attachments` in `message`
            - `list_path` (string)
          - `from` (string)
          - `icon` (string)
          - `text` (string)
          - `to` ([] string)
      - `webhook` ({} WebhookAction)
        - `auth` ({} HttpInputAuthentication)
          - `basic` ({} HttpInputBasicAuthentication)
            - `password` (string)
            - `username` (string)
        - `body` (string)
        - `connection_timeout` (string Duration)
        - `headers` (map string to string)
        - `host` (string)
        - `method` (enum HttpInputMethod)
          Values: `head`, `get`, `post`, `put`, `delete`
        - `params` (map string to string)
        - `path` (string)
        - `port` (number uint)
        - `proxy` ({} HttpInputProxy)
          - `host` (string)
          - `port` (number uint)
        - `read_timeout` (string Duration)
        - `scheme` (enum ConnectionScheme)
          Values: `http`, `https`
        - `url` (string)
    - `condition` ({} ConditionContainer)
      Same fields as `condition` in `actions`
    - `input` ({} InputContainer)
      - `chain` ({} ChainInput)
        - `inputs` ([] string to InputContainer) — recursive
          Same fields as `input` in `watch`
      - `http` ({} HttpInput)
        - `extract` ([] string)
        - `request` ({} HttpInputRequestDefinition)
          Same fields as `request` in `http`
        - `response_content_type` (enum ResponseContentType)
          Values: `json`, `yaml`, `text`
      - `search` ({} SearchInput)
        - `extract` ([] string)
        - `request` ({} SearchInputRequestDefinition)
          Same fields as `request` in `search`
        - `timeout` (string Duration)
      - `simple` (map string to object)
    - `metadata` (Metadata)
    - `status` ({} WatchStatus)
      - `actions` (Actions)
      - `last_checked` (DateTime)
      - `last_met_condition` (DateTime)
      - `state` ({} ActivationState)
        - `active` (boolean)
        - `timestamp` (DateTime)
      - `version` (number VersionNumber)
      - `execution_state` (string)
    - `throttle_period` (string Duration)
    - `throttle_period_in_millis` (DurationValueUnitMillis)
    - `transform` ({} TransformContainer)
      Same fields as `transform` in `actions`
    - `trigger` ({} TriggerContainer)
      - `schedule` ({} ScheduleContainer)
        - `timezone` (string)
        - `cron` (string)
        - `daily` ({} DailySchedule)
          - `at` ([] union ScheduleTimeOfDay)
            - **string**
            - **HourAndMinute**
              - `hour` ([] number)
              - `minute` ([] number)
        - `hourly` ({} HourlySchedule)
          - `minute` ([] number)
        - `interval` (string Duration)
        - `monthly` (union oneOf)
          `TimeOfMonth` or `TimeOfMonth[]`
          - `at` ([] string)
          - `on` ([] number)
        - `weekly` (union oneOf)
          `TimeOfWeek` or `TimeOfWeek[]`
          - `at` ([] string)
          - `on` ([] enum Day)
            Values: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`
        - `yearly` (union oneOf)
          `TimeOfYear` or `TimeOfYear[]`
          - `at` ([] string)
          - `int` ([] enum Month)
            Values: `january`, `february`, `march`, `april`, `may`, `june`, `july`, `august`, `september`, `october`, `november`, `december`
          - `on` ([] number)
  - `_primary_term` (number)
  - `_seq_no` (number SequenceNumber)
## Code Examples

#### Console

```console
POST /_watcher/_query/watches
```

#### JavaScript

```javascript
const response = await client.watcher.queryWatches();
```

#### Python

```python
resp = client.watcher.query_watches()
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_watcher/_query/watches" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.watcher().queryWatches();
```

#### PHP

```php
$resp = $client->watcher()->queryWatches();
```

#### Ruby

```ruby
response = client.watcher.query_watches
```

## Response Examples

#### Watcher query watches response example1

A successful response from `GET /_watcher/_query/watches`.

```json
{
  "count": 1,
  "watches": [
      {
          "_id": "my_watch",
          "watch": {
              "trigger": {
                  "schedule": {
                      "hourly": {
                          "minute": [
                              0,
                              5
                          ]
                      }
                  }
              },
              "input": {
                  "simple": {
                      "payload": {
                          "send": "yes"
                      }
                  }
              },
              "condition": {
                  "always": {}
              },
              "actions": {
                  "test_index": {
                      "index": {
                          "index": "test"
                      }
                  }
              }
          },
          "status": {
              "state": {
                  "active": true,
                  "timestamp": "2015-05-26T18:21:08.630Z"
              },
              "actions": {
                  "test_index": {
                      "ack": {
                          "timestamp": "2015-05-26T18:21:08.630Z",
                          "state": "awaits_successful_execution"
                      }
                  }
              },
              "version": -1
          },
          "_seq_no": 0,
          "_primary_term": 1
      }
  ]
}
```