elasticsearch/docs/reference/rest-api/watcher/query-watches.asciidoc

[role="xpack"]
[[watcher-api-query-watches]]
=== Query watches API
++++
<titleabbrev>Query watches</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-watcher[{watcher} APIs].
--

Retrieves all registered watches.

[[watcher-api-query-watches-request]]
==== {api-request-title}

`GET /_watcher/_query/watches`

[[watcher-api-query-watches-prereqs]]
==== {api-prereq-title}

* You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
this API. For more information, see <<security-privileges>>.

//[[watcher-api-query-watches-desc]]
//==== {api-description-title}

Retrieves all watches in a paginated manner and
optionally filtering watches by a query.

//[[watcher-api-query-watches-request-body]]
//==== {api-request-body-title}

This API supports the following fields:

[cols=",^,^,", options="header"]
|======
| Name              | Required | Default  | Description

| `from`            | no       | 0        | The offset from the first result to fetch. Needs to be non-negative.

| `size`            | no       | 10       | The number of hits to return. Needs to be non-negative.

| `query`           | no       | null     | Optional, <<query-dsl,query>> filter watches to be returned.

| `sort`            | no       | null     | Optional <<sort-search-results,sort definition>>.

| `search_after`    | no       | null     | Optional <<search-after,search After>> to do pagination
                                            using last hit's sort values.
|======

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

//[[watcher-api-query-watches-response-body]]
//==== {api-response-body-title}

This api returns the following top level fields:

`count`::
    The total number of watches found.

`watches`::
    A list of watches based on the `from`, `size` or `search_after` request body parameters.

[[watcher-api-query-watches-example]]
==== {api-examples-title}

The following example list all stored watches:

[source,console]
--------------------------------------------------
GET /_watcher/_query/watches
--------------------------------------------------
// TEST[setup:my_active_watch]

Response:

[source,console-result]
--------------------------------------------------
{
    "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
        }
    ]
}
--------------------------------------------------
// TESTRESPONSE[s/"timestamp": "2015-05-26T18:21:08.630Z"/"timestamp": "$body.watches.0.status.state.timestamp"/]