Run a watch Generally available

POST /_watcher/watch/{id}/_execute

All methods and paths for this operation:

PUT /_watcher/watch/_execute

POST /_watcher/watch/_execute
PUT /_watcher/watch/{id}/_execute
POST /_watcher/watch/{id}/_execute

This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing and debugging your watches prior to adding them to Watcher.

When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches. If your user is allowed to read index a, but not index b, then the exact same set of rules will apply during execution of a watch.

When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch. Refer to the external documentation for examples of watch execution requests, including existing, customized, and inline watches.

Required authorization

  • Cluster privileges: manage_watcher
External documentation

Path parameters

  • id string Required

    The watch identifier.

Query parameters

  • debug boolean

    Defines whether the watch runs in debug mode.

application/json

Body

  • action_modes object

    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_input object

    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_condition boolean

    When set to true, the watch execution uses the always condition. This can also be specified as an HTTP parameter.

    Default value is false.

  • record_execution boolean

    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.

    Default value is false.

  • simulated_actions object
    Hide simulated_actions attributes Show simulated_actions attributes object
    • actions array[string] Required
    • all object Required
    • use_all boolean Required
  • trigger_data object

    This structure is parsed as the data of the trigger event that will be used during the watch execution.

    Hide trigger_data attributes Show trigger_data attributes object
  • watch object

    When present, this watch is used instead of the one specified in the request. This watch is not persisted to the index and record_execution cannot be set.

    Hide watch attributes Show watch attributes object
    • actions object Required
      Hide actions attribute Show actions attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • action_type string

          Values are email, webhook, index, logging, slack, or pagerduty.

        • condition object
          Hide condition attributes Show condition attributes object
          • array_compare object
          • compare object
        • foreach string
        • max_iterations number
        • name string
        • 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.

        • Time unit for milliseconds

        • transform object
          Hide transform attribute Show transform attribute object
          • chain array[object]
        • index object
        • logging object
          Hide logging attributes Show logging attributes object
          • level string
          • text string Required
          • category string
        • slack object
          Hide slack attribute Show slack attribute object
          • account string
    • condition object Required
      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
          • path string Required
      • compare object
        Hide compare attribute Show compare attribute object
        • * object Additional properties
      • never object
      • script object
        Hide script attributes Show script attributes object
        • params object
        • id string
    • input object Required
      Hide input attributes Show input attributes object
      • chain object
        Hide chain attribute Show chain attribute object
        • inputs array[object] Required
      • http object
        Hide http attribute Show http attribute object
        • extract array[string]
      • simple object
        Hide simple attribute Show simple attribute object
        • * object Additional properties
    • metadata object
      Hide metadata attribute Show metadata attribute object
      • * object Additional properties
    • status object
      Hide status attributes Show status attributes object
      • actions object Required
        Hide actions attribute Show actions attribute object
        • * object Additional properties
      • last_checked string
      • last_met_condition string
      • state object Required
        Hide state attribute Show state attribute object
        • active boolean Required
      • version number Required
      • execution_state string
    • 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.

    • 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
        • lang string

          Default value is painless.

        • params object
        • id string
    • trigger object Required
      Hide trigger attribute Show trigger attribute object
      • schedule object
        Hide schedule attributes Show schedule attributes object
        • timezone string
        • monthly
        • weekly
        • yearly

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _id string Required

      The watch record identifier as it would be stored in the .watcher-history index.

    • watch_record object Required

      The watch record document as it would be stored in the .watcher-history index.

      Hide watch_record attributes Show watch_record attributes object
      • condition object Required
        Hide condition attributes Show condition attributes object
        • always object
        • array_compare object
          Hide array_compare attribute Show array_compare attribute object
          • * object Additional properties
        • compare object
          Hide compare attribute Show compare attribute object
          • * object Additional properties
        • never object
        • script object
      • input object Required
        Hide input attributes Show input attributes object
        • chain object
        • http object
        • simple object
          Hide simple attribute Show simple attribute object
          • * object Additional properties
      • messages array[string] Required
      • metadata object
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • node string Required
      • result object Required
        Hide result attributes Show result attributes object
        • actions array[object] Required
        • condition object Required
        • execution_time
        • input object Required
      • state string Required

        Values are awaits_execution, checking, execution_not_needed, throttled, executed, failed, deleted_while_queued, or not_executed_already_queued.

      • trigger_event object Required
        Hide trigger_event attributes Show trigger_event attributes object
        • manual object Required
        • triggered_time
        • type string Required
      • user string Required
      • watch_id string Required
      • status object
        Hide status attributes Show status attributes object
        • actions object Required
        • last_checked
        • last_met_condition
        • state object Required
        • version number Required
        • execution_state string
POST /_watcher/watch/{id}/_execute
POST _watcher/watch/my_watch/_execute
{
  "trigger_data" : { 
    "triggered_time" : "now",
    "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}
resp = client.watcher.execute_watch(
    id="my_watch",
    trigger_data={
        "triggered_time": "now",
        "scheduled_time": "now"
    },
    alternative_input={
        "foo": "bar"
    },
    ignore_condition=True,
    action_modes={
        "my-action": "force_simulate"
    },
    record_execution=True,
)
const response = await client.watcher.executeWatch({
  id: "my_watch",
  trigger_data: {
    triggered_time: "now",
    scheduled_time: "now",
  },
  alternative_input: {
    foo: "bar",
  },
  ignore_condition: true,
  action_modes: {
    "my-action": "force_simulate",
  },
  record_execution: true,
});
response = client.watcher.execute_watch(
  id: "my_watch",
  body: {
    "trigger_data": {
      "triggered_time": "now",
      "scheduled_time": "now"
    },
    "alternative_input": {
      "foo": "bar"
    },
    "ignore_condition": true,
    "action_modes": {
      "my-action": "force_simulate"
    },
    "record_execution": true
  }
)
$resp = $client->watcher()->executeWatch([
    "id" => "my_watch",
    "body" => [
        "trigger_data" => [
            "triggered_time" => "now",
            "scheduled_time" => "now",
        ],
        "alternative_input" => [
            "foo" => "bar",
        ],
        "ignore_condition" => true,
        "action_modes" => [
            "my-action" => "force_simulate",
        ],
        "record_execution" => true,
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"trigger_data":{"triggered_time":"now","scheduled_time":"now"},"alternative_input":{"foo":"bar"},"ignore_condition":true,"action_modes":{"my-action":"force_simulate"},"record_execution":true}' "$ELASTICSEARCH_URL/_watcher/watch/my_watch/_execute"
client.watcher().executeWatch(e -> e
    .actionModes("my-action", ActionExecutionMode.ForceSimulate)
    .alternativeInput("foo", JsonData.fromJson("\"bar\""))
    .id("my_watch")
    .ignoreCondition(true)
    .recordExecution(true)
    .triggerData(t -> t
        .scheduledTime(DateTime.of("now"))
        .triggeredTime(DateTime.of("now"))
    )
);
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" 
  }
}