Run a watch | Elasticsearch API documentation (v8)

Query parameters

debugboolean
Defines whether the watch runs in debug mode.

application/json

Body

action_modesobject
Determines how to handle the watch actions as part of the watch execution.
Hide action_modes attribute Show action_modes attribute object
- *string Additional properties
  Values are simulate, force_simulate, execute, force_execute, or skip.
alternative_inputobject
When present, the watch uses this object as a payload instead of executing its own input.
Hide alternative_input attribute Show alternative_input attribute object
- *object Additional properties
ignore_conditionboolean
When set to true, the watch execution uses the always condition. This can also be specified as an HTTP parameter.
record_executionboolean
When set to true, the watch record representing the watch execution result is persisted to the .watcher-history index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent runs. This can also be specified as an HTTP parameter.
simulated_actionsobject
Hide simulated_actions attributes Show simulated_actions attributes object
- actionsarray[string] Required
- allobject Required
- use_allboolean Required
trigger_dataobject
Hide trigger_data attributes Show trigger_data attributes object
- scheduled_timestring | number Required
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  One of:
  DateTimestring UnitMillisnumber
  Time unit for milliseconds
- triggered_timestring | number
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  One of:
  DateTimestring UnitMillisnumber
  Time unit for milliseconds
watchobject
Hide watch attributes Show watch attributes object
- actionsobject Required
  Hide actions attribute Show actions attribute object
  *object Additional properties
  Hide * attributes Show * attributes object
  action_typestring
  Values are email, webhook, index, logging, slack, or pagerduty.
  conditionobject
  Hide condition attributes Show condition attributes object
  alwaysobject
  array_compareobject
  Hide array_compare attribute Show array_compare attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  pathstring Required
  compareobject
  Hide compare attribute Show compare attribute object
  *object Additional properties
  neverobject
  scriptobject
  Hide script attributes Show script attributes object
  langstring
  paramsobject
  Hide params attribute Show params attribute object
  *object Additional properties
  sourcestring
  idstring
  foreachstring
  max_iterationsnumber
  namestring
  throttle_periodstring
  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_millisnumber
  Time unit for milliseconds
  transformobject
  Hide transform attributes Show transform attributes object
  chainarray[object]
  scriptobject
  Hide script attributes Show script attributes object
  langstring
  paramsobject
  Hide params attribute Show params attribute object
  *object Additional properties
  sourcestring
  idstring
  searchobject
  Hide search attributes Show search attributes object
  requestobject Required
  Hide request attributes Show request attributes object
  bodyobject
  indicesarray[string]
  indices_optionsobject
  search_typestring
  Values are query_then_fetch or dfs_query_then_fetch.
  templateobject
  rest_total_hits_as_intboolean
  timeoutstring 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.
  indexobject
  Hide index attributes Show index attributes object
  indexstring Required
  doc_idstring
  refreshstring
  Values are true, false, or wait_for.
  op_typestring
  Values are index or create.
  timeoutstring
  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.
  execution_time_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  loggingobject
  Hide logging attributes Show logging attributes object
  levelstring
  textstring Required
  categorystring
  emailobject
  Hide email attributes Show email attributes object
  idstring
  bccstring | array[string]
  One of:
  string-1string array-2array[string]
  bodyobject
  Hide body attributes Show body attributes object
  htmlstring
  textstring
  ccstring | array[string]
  One of:
  string-1string array-2array[string]
  fromstring
  prioritystring
  Values are lowest, low, normal, high, or highest.
  reply_tostring | array[string]
  One of:
  string-1string array-2array[string]
  sent_datestring
  subjectstring Required
  tostring | array[string] Required
  One of:
  string-1string array-2array[string]
  attachmentsobject
  Hide attachments attribute Show attachments attribute object
  *object Additional properties
  pagerdutyobject
  Hide pagerduty attributes Show pagerduty attributes object
  accountstring
  attach_payloadboolean Required
  clientstring
  client_urlstring
  contextsarray[object]
  descriptionstring Required
  event_typestring
  Values are trigger, resolve, or acknowledge.
  incident_keystring Required
  proxyobject
  Hide proxy attributes Show proxy attributes object
  hoststring
  portnumber
  slackobject
  Hide slack attributes Show slack attributes object
  accountstring
  messageobject Required
  Hide message attributes Show message attributes object
  attachmentsarray[object] Required
  dynamic_attachmentsobject
  Hide dynamic_attachments attributes Show dynamic_attachments attributes object
  attachment_templateobject Required
  list_pathstring Required
  fromstring Required
  iconstring
  textstring Required
  toarray[string] Required
  webhookobject
  Hide webhook attributes Show webhook attributes object
  authobject
  Hide auth attribute Show auth attribute object
  basicobject Required
  bodystring
  connection_timeoutstring
  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.
  headersobject
  Hide headers attribute Show headers attribute object
  hoststring
  methodstring
  Values are head, get, post, put, or delete.
  paramsobject
  Hide params attribute Show params attribute object
  *string Additional properties
  pathstring
  portnumber
  proxyobject
  Hide proxy attributes Show proxy attributes object
  hoststring Required
  portnumber Required
  read_timeoutstring
  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.
  schemestring
  Values are http or https.
  urlstring
- conditionobject Required
  Hide condition attributes Show condition attributes object
  alwaysobject
  array_compareobject
  Hide array_compare attribute Show array_compare attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  pathstring Required
  compareobject
  Hide compare attribute Show compare attribute object
  *object Additional properties
  neverobject
  scriptobject
  Hide script attributes Show script attributes object
  langstring
  paramsobject
  Hide params attribute Show params attribute object
  *object Additional properties
  sourcestring
  idstring
- inputobject Required
  Hide input attributes Show input attributes object
  chainobject
  Hide chain attribute Show chain attribute object
  inputsarray[object] Required
  Hide inputs attribute Show inputs attribute object
  *object
  httpobject
  Hide http attributes Show http attributes object
  extractarray[string]
  requestobject
  Hide request attributes Show request attributes object
  authobject
  Hide auth attribute Show auth attribute object
  basicobject Required
  Hide basic attributes Show basic attributes object
  passwordstring Required
  usernamestring Required
  bodystring
  connection_timeoutstring
  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.
  headersobject
  Hide headers attribute Show headers attribute object
  hoststring
  methodstring
  Values are head, get, post, put, or delete.
  paramsobject
  Hide params attribute Show params attribute object
  *string Additional properties
  pathstring
  portnumber
  proxyobject
  Hide proxy attributes Show proxy attributes object
  hoststring Required
  portnumber Required
  read_timeoutstring
  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.
  schemestring
  Values are http or https.
  urlstring
  response_content_typestring
  Values are json, yaml, or text.
  searchobject
  Hide search attributes Show search attributes object
  extractarray[string]
  requestobject Required
  Hide request attributes Show request attributes object
  bodyobject
  Hide body attribute Show body attribute object
  queryobject Required
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  indicesarray[string]
  indices_optionsobject
  Hide indices_options attributes Show indices_options attributes object
  allow_no_indicesboolean
  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_wildcardsstring | array[string]
  ignore_unavailableboolean
  If true, missing or closed indices are not included in the response.
  ignore_throttledboolean
  If true, concrete, expanded or aliased indices are ignored when frozen.
  search_typestring
  Values are query_then_fetch or dfs_query_then_fetch.
  templateobject
  Hide template attributes Show template attributes object
  explainboolean
  idstring
  paramsobject
  Hide params attribute Show params attribute object
  *object Additional properties
  profileboolean
  sourcestring
  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_intboolean
  timeoutstring
  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.
  simpleobject
  Hide simple attribute Show simple attribute object
  *object Additional properties
- metadataobject
  Hide metadata attribute Show metadata attribute object
- statusobject
  Hide status attributes Show status attributes object
  actionsobject Required
  Hide actions attribute Show actions attribute object
  *object Additional properties
  Hide * attributes Show * attributes object
  ackobject Required
  Hide ack attributes Show ack attributes object
  statestring Required
  Values are awaits_successful_execution, ackable, or acked.
  timestampstring
  last_executionobject
  Hide last_execution attributes Show last_execution attributes object
  successfulboolean Required
  timestampstring
  reasonstring
  last_successful_executionobject
  Hide last_successful_execution attributes Show last_successful_execution attributes object
  successfulboolean Required
  timestampstring
  reasonstring
  last_throttleobject
  Hide last_throttle attributes Show last_throttle attributes object
  reasonstring Required
  timestampstring
  last_checkedstring | number
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  One of:
  DateTimestring UnitMillisnumber
  Time unit for milliseconds
  last_met_conditionstring | number
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  One of:
  DateTimestring UnitMillisnumber
  Time unit for milliseconds
  stateobject Required
  Hide state attributes Show state attributes object
  activeboolean Required
  timestampstring | number Required
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  One of:
  DateTimestring UnitMillisnumber
  Time unit for milliseconds
  versionnumber Required
  execution_statestring
- throttle_periodstring
  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_millisnumber
  Time unit for milliseconds
- transformobject
  Hide transform attributes Show transform attributes object
  chainarray[object]
  scriptobject
  Hide script attributes Show script attributes object
  langstring
  paramsobject
  Hide params attribute Show params attribute object
  *object Additional properties
  sourcestring
  idstring
  searchobject
  Hide search attributes Show search attributes object
  requestobject Required
  Hide request attributes Show request attributes object
  bodyobject
  Hide body attribute Show body attribute object
  queryobject Required
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  indicesarray[string]
  indices_optionsobject
  Hide indices_options attributes Show indices_options attributes object
  allow_no_indicesboolean
  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_wildcardsstring | array[string]
  ignore_unavailableboolean
  If true, missing or closed indices are not included in the response.
  ignore_throttledboolean
  If true, concrete, expanded or aliased indices are ignored when frozen.
  search_typestring
  Values are query_then_fetch or dfs_query_then_fetch.
  templateobject
  Hide template attributes Show template attributes object
  explainboolean
  idstring
  paramsobject
  Hide params attribute Show params attribute object
  *object Additional properties
  profileboolean
  sourcestring
  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_intboolean
  timeoutstring 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.
- triggerobject Required
  Hide trigger attribute Show trigger attribute object
  scheduleobject
  Hide schedule attributes Show schedule attributes object
  timezonestring
  cronstring
  dailyobject
  Hide daily attribute Show daily attribute object
  atarray[string | object] Required
  A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.
  A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.
  One of:
  ScheduleTimeOfDaystring HourAndMinuteobject
  hourlyobject
  Hide hourly attribute Show hourly attribute object
  minutearray[number] Required
  intervalstring
  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.
  monthlyobject | array[object]
  One of:
  TimeOfMonthobject array-2array[object]
  Hide attributes Show attributes object
  atarray[string] Required
  onarray[number] Required
  weeklyobject | array[object]
  One of:
  TimeOfWeekobject array-2array[object]
  Hide attributes Show attributes object
  atarray[string] Required
  onarray[string] Required
  Values are sunday, monday, tuesday, wednesday, thursday, friday, or saturday.
  yearlyobject | array[object]
  One of:
  TimeOfYearobject array-2array[object]
  Hide attributes Show attributes object
  atarray[string] Required
  intarray[string] Required
  Values are january, february, march, april, may, june, july, august, september, october, november, or december.
  onarray[number] Required

Run `POST _watcher/watch/my_watch/_execute` to run a watch. The input defined in the watch is ignored and the `alternative_input` is used as the payload. The condition as defined by the watch is ignored and is assumed to evaluate to true. The `force_simulate` action forces the simulation of `my-action`. Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being run normally.

{
  "trigger_data" : { 
    "triggered_time" : "now",
    "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}

Run `POST _watcher/watch/my_watch/_execute` and set a different mode for each action.

{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}

Run `POST _watcher/watch/_execute` to run a watch inline. All other settings for this API still apply when inlining a watch. In this example, while the inline watch defines a compare condition, during the execution this condition will be ignored.

{
  "watch" : {
    "trigger" : { "schedule" : { "interval" : "10s" } },
    "input" : {
      "search" : {
        "request" : {
          "indices" : [ "logs" ],
          "body" : {
            "query" : {
              "match" : { "message": "error" }
            }
          }
        }
      }
    },
    "condition" : {
      "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
    },
    "actions" : {
      "log_error" : {
        "logging" : {
          "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
        }
      }
    }
  }
}

Response examples (200)

A successful response from `POST _watcher/watch/my_watch/_execute`.

{
  "_id": "my_watch_0-2015-06-02T23:17:55.124Z", 
  "watch_record": { 
    "@timestamp": "2015-06-02T23:17:55.124Z",
    "watch_id": "my_watch",
    "node": "my_node",
    "messages": [],
    "trigger_event": {
      "type": "manual",
      "triggered_time": "2015-06-02T23:17:55.124Z",
      "manual": {
        "schedule": {
          "scheduled_time": "2015-06-02T23:17:55.124Z"
        }
      }
    },
    "state": "executed",
    "status": {
      "version": 1,
      "execution_state": "executed",
      "state": {
        "active": true,
        "timestamp": "2015-06-02T23:17:55.111Z"
      },
      "last_checked": "2015-06-02T23:17:55.124Z",
      "last_met_condition": "2015-06-02T23:17:55.124Z",
      "actions": {
        "test_index": {
          "ack": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "state": "ackable"
          },
          "last_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          },
          "last_successful_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          }
        }
      }
    },
    "input": {
      "simple": {
        "payload": {
          "send": "yes"
        }
      }
    },
    "condition": {
      "always": {}
    },
    "result": { 
      "execution_time": "2015-06-02T23:17:55.124Z",
      "execution_duration": 12608,
      "input": {
        "type": "simple",
        "payload": {
          "foo": "bar"
        },
        "status": "success"
      },
      "condition": {
        "type": "always",
        "met": true,
        "status": "success"
      },
      "actions": [
        {
          "id": "test_index",
          "index": {
            "response": {
              "index": "test",
              "version": 1,
              "created": true,
              "result": "created",
              "id": "AVSHKzPa9zx62AzUzFXY"
            }
          },
          "status": "success",
          "type": "index"
        }
      ]
    },
    "user": "test_admin" 
  }
}

Query parameters

Body

scheduled_timestring | number Required

triggered_timestring | number

bccstring | array[string]

ccstring | array[string]

reply_tostring | array[string]

tostring | array[string] Required

last_checkedstring | number

last_met_conditionstring | number

timestampstring | number Required

monthlyobject | array[object]

weeklyobject | array[object]

yearlyobject | array[object]

Responses

execution_timestring | number Required

triggered_timestring | number Required

last_checkedstring | number

last_met_conditionstring | number

timestampstring | number Required