Create or update a watch

PUT /_watcher/watch/{id}
Api key auth Basic auth Bearer auth

When a watch is registered, a new document that represents the watch is added to the .watches index and its trigger is immediately registered with the relevant trigger engine. Typically for the schedule trigger, the scheduler is the trigger engine.

IMPORTANT: You must use Kibana or this API to create a watch. Do not add a watch directly to the .watches index by using the Elasticsearch index API. If Elasticsearch security features are enabled, do not give users write privileges on the .watches index.

When you add a watch you can also define its initial active state by setting the active parameter.

When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges. If the user is able to read index a, but not index b, the same will apply when the watch runs.

Path parameters

  • id string Required

    The identifier for the watch.

Query parameters

  • active boolean

    The initial state of the watch. The default value is true, which means the watch is active by default.

  • if_primary_term number

    only update the watch if the last operation that has changed the watch has the specified primary term

  • if_seq_no number

    only update the watch if the last operation that has changed the watch has the specified sequence number

  • version number

    Explicit version number for concurrency control

application/json

Body

  • actions object

    The list of actions that will be run if the condition matches.

    Hide actions attribute Show actions attribute object
  • condition object
    Hide condition attributes Show condition attributes object
    • always object
    • array_compare object
      Hide array_compare attribute Show array_compare attribute object
      • * object Additional properties
        Hide * attribute Show * attribute object
    • compare object
      Hide compare attribute Show compare attribute object
      • * object Additional properties
    • never object
    • script object
      Hide script attributes Show script attributes object
  • input object
    Hide input attributes Show input attributes object
    • chain object
      Hide chain attribute Show chain attribute object
      • inputs array[object] Required
        Hide inputs attribute Show inputs attribute object
    • http object
      Hide http attributes Show http attributes object
      • extract array[string]
      • request object
        Hide request attributes Show request attributes object
        • auth object
          Hide auth attribute Show auth attribute object
        • body string
        • connection_timeout string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • headers object
          Hide headers attribute Show headers attribute object
          • * string Additional properties
        • host string
        • method string

          Values are head, get, post, put, or delete.

        • params object
          Hide params attribute Show params attribute object
          • * string Additional properties
        • path string
        • port number
        • proxy object
          Hide proxy attributes Show proxy attributes object
        • read_timeout string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        • scheme string

          Values are http or https.

        • url string
      • response_content_type string

        Values are json, yaml, or text.

    • search object
      Hide search attributes Show search attributes object
      • extract array[string]
      • request object Required
        Hide request attributes Show request attributes object
        • body object
          Hide body attribute Show body attribute object
        • indices array[string]
        • indices_options object
          Hide indices_options attributes Show indices_options attributes object
          • 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 | array[string]
          • ignore_unavailable boolean

            If true, missing or closed indices are not included in the response.

          • ignore_throttled boolean

            If true, concrete, expanded or aliased indices are ignored when frozen.

        • search_type string

          Values are query_then_fetch or dfs_query_then_fetch.

        • template object
          Hide template attributes Show template attributes object
          • explain boolean
          • id string
          • params object
            Hide params attribute Show params attribute object
            • * object Additional properties
          • profile boolean
          • 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

        A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • simple object
      Hide simple attribute Show simple attribute object
      • * object Additional properties
  • metadata object
    Hide metadata attribute Show metadata attribute object
    • * object Additional properties
  • throttle_period string

    A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • throttle_period_in_millis number

    Time unit for milliseconds

  • transform object
    Hide transform attributes Show transform attributes object
    • chain array[object]
    • script object
      Hide script attributes Show script attributes object
    • search object
      Hide search attributes Show search attributes object
      • request object Required
        Hide request attributes Show request attributes object
        • body object
          Hide body attribute Show body attribute object
        • indices array[string]
        • indices_options object
          Hide indices_options attributes Show indices_options attributes object
          • 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 | array[string]
          • ignore_unavailable boolean

            If true, missing or closed indices are not included in the response.

          • ignore_throttled boolean

            If true, concrete, expanded or aliased indices are ignored when frozen.

        • search_type string

          Values are query_then_fetch or dfs_query_then_fetch.

        • template object
          Hide template attributes Show template attributes object
          • explain boolean
          • id string
          • params object
            Hide params attribute Show params attribute object
            • * object Additional properties
          • profile boolean
          • 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 Required

        A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • trigger object
    Hide trigger attribute Show trigger attribute object
    • schedule object
      Hide schedule attributes Show schedule attributes object

Responses

PUT /_watcher/watch/{id} 
curl \
 --request PUT 'http://api.example.com/_watcher/watch/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"trigger\" : {\n    \"schedule\" : { \"cron\" : \"0 0/1 * * * ?\" }\n  },\n  \"input\" : {\n    \"search\" : {\n      \"request\" : {\n        \"indices\" : [\n          \"logstash*\"\n        ],\n        \"body\" : {\n          \"query\" : {\n            \"bool\" : {\n              \"must\" : {\n                \"match\": {\n                  \"response\": 404\n                }\n              },\n              \"filter\" : {\n                \"range\": {\n                  \"@timestamp\": {\n                    \"from\": \"{{ctx.trigger.scheduled_time}}||-5m\",\n                    \"to\": \"{{ctx.trigger.triggered_time}}\"\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  \"condition\" : {\n    \"compare\" : { \"ctx.payload.hits.total\" : { \"gt\" : 0 }}\n  },\n  \"actions\" : {\n    \"email_admin\" : {\n      \"email\" : {\n        \"to\" : \"admin@domain.host.com\",\n        \"subject\" : \"404 recently encountered\"\n      }\n    }\n  }\n}"'
Request example
Run `PUT _watcher/watch/my-watch` add a watch. The watch schedule triggers every minute. The watch search input looks for any 404 HTTP responses that occurred in the last five minutes. The watch condition checks if any search hits where found. When found, the watch action sends an email to an administrator. 
{
  "trigger" : {
    "schedule" : { "cron" : "0 0/1 * * * ?" }
  },
  "input" : {
    "search" : {
      "request" : {
        "indices" : [
          "logstash*"
        ],
        "body" : {
          "query" : {
            "bool" : {
              "must" : {
                "match": {
                  "response": 404
                }
              },
              "filter" : {
                "range": {
                  "@timestamp": {
                    "from": "{{ctx.trigger.scheduled_time}}||-5m",
                    "to": "{{ctx.trigger.triggered_time}}"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "condition" : {
    "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
  },
  "actions" : {
    "email_admin" : {
      "email" : {
        "to" : "admin@domain.host.com",
        "subject" : "404 recently encountered"
      }
    }
  }
}
Response examples (200) 
{
  "created": true,
  "_id": "string",
  "_primary_term": 42.0,
  "_seq_no": 42.0,
  "_version": 42.0
}