Create or update a watch

POST also PUT /_watcher/watch/{id}

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.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Path parameters

Query parameters

Request body

actions map string to object: The list of actions that will be run if the condition matches.
condition object: The condition that defines if the actions should be run.; Same fields as condition in actions
input object: The input that defines the input that loads the data for the watch.
metadata object: Metadata JSON that will be copied into the history entries.
throttle_period string: The minimum time between actions being run. The default is 5 seconds. This default can be changed in the config file with the setting xpack.watcher.throttle.period.default_period. If both this value and the throttle_period_in_millis parameter are specified, Watcher uses the last parameter included in the request.
throttle_period_in_millis number: Minimum time in milliseconds between actions being run. Defaults to 5000. If both this value and the throttle_period parameter are specified, Watcher uses the last parameter included in the request.
transform object: The transform that processes the watch payload to prepare it for the watch actions.; Same fields as transform in actions
trigger object: The trigger that defines when the watch should run.

Response

application/json

Examples

Request Console 1 / 7 languages

Run POST _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.

Console Kibana Dev Tools

POST _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"
      }
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.watcher.putWatch({
  id: "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",
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.watcher.put_watch(
    id="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"
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_watcher/watch/my-watch" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
        }
      }
    }
  }'

Java Elasticsearch Java Client

client.watcher().putWatch(p -> p
    .actions("email_admin", a -> a
        .email(e -> e
            .subject("404 recently encountered")
            .to("admin@domain.host.com")
        )
    )
    .condition(c -> c
        .compare(NamedValue.of("ctx.payload.hits.total",Pair.of(ConditionOp.Gt,FieldValue.of(0))))
    )
    .id("my-watch")
    .input(i -> i
        .search(s -> s
            .request(r -> r
                .body(b -> b
                    .query(q -> q
                        .bool(bo -> bo
                            .filter(f -> f
                                .range(ra -> ra
                                    .untyped(u -> u
                                        .field("@timestamp")
                                    )
                                )
                            )
                            .must(m -> m
                                .match(ma -> ma
                                    .field("response")
                                    .query(FieldValue.of(404))
                                )
                            )
                        )
                    )
                )
                .indices("logstash*")
            )
        )
    )
    .trigger(t -> t
        .schedule(sc -> sc
            .cron("0 0/1 * * * ?")
        )
    )
);

PHP Elasticsearch PHP Client

$resp = $client->watcher()->putWatch([
    "id" => "my-watch",
    "body" => [
        "trigger" => [
            "schedule" => [
                "cron" => "0 0/1 * * * ?",
            ],
        ],
        "input" => [
            "search" => [
                "request" => [
                    "indices" => array(
                        "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",
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.watcher.put_watch(
  id: "my-watch",
  body: {
    "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

No example

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body