New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 6.2 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Watcher APIs Get Watch API »
Elastic Docs ›Elasticsearch Reference [6.2] ›X-Pack APIs ›Watcher APIs

Put Watch API

Put Watch API

The PUT watch API either registers a new watch in Watcher or update an existing one.

Request

PUT _xpack/watcher/watch/<watch_id>

Description

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.

Putting a watch must be done via this API only. Do not put a watch directly to the .watches index using the Elasticsearch Index API. If X-Pack security is enabled, make sure no write privileges are granted to anyone over the .watches index.

When adding a watch you can also define its initial active state. You do that by setting the active parameter.

Path Parameters

watch_id (required)
(string) Identifier for the watch.

Query Parameters

active
(boolean) Defines whether the watch is active or inactive by default. The default value is true, which means the watch is active by default.

Request Body

A watch has the following fields:

Name Description

trigger

The trigger that defines when the watch should run.

input

The input that defines the input that loads the data for the watch.

condition

The condition that defines if the actions should be run.

actions

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

metadata

Metadata json that will be copied into the history entries.

throttle_period

The minimum time between actions being run, the default for this is 5 seconds. This default can be changed in the config file with the setting xpack.watcher.throttle.period.default_period.

Authorization

You must have manage_watcher cluster privileges to use this API. For more information, see Security Privileges.

Security Integration

When X-Pack security is enabled, your watch will only be able to index or search 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 is executed.

Examples

The following example adds a watch with the my-watch id that has the following characteristics:

  • 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. 
PUT _xpack/watcher/watch/my-watch
{
  "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"
      }
    }
  }
}
Copy as curlTry in Elastic 

When you add a watch you can also define its initial active state. You do that by setting the active parameter. The following command adds a watch and sets it to be inactive by default:

PUT _xpack/watcher/watch/my-watch?active=false

If you omit the active parameter, the watch is active by default.

« Watcher APIs Get Watch API »