› › ›

Ack watch API

Acknowledging a watch enables you to manually throttle execution of the watch’s actions.

Request

PUT _watcher/watch/<watch_id>/_ack

PUT _watcher/watch/<watch_id>/_ack/<action_id>

Prerequisites

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

Description

An action’s acknowledgement state is stored in the status.actions.<id>.ack.state structure.

If the specified watch is currently being executed, this API will return an error. The reason for this is to prevent overwriting of the watch status from a watch execution.

Path parameters

<action_id>: (Optional, list) A comma-separated list of the action IDs to acknowledge. If you omit this parameter, all of the actions of the watch are acknowledged.
<watch_id>: (Required, string) Identifier for the watch.

Examples

To demonstrate let’s create a new watch:

resp = client.watcher.put_watch(
    id="my_watch",
    trigger={
        "schedule": {
            "yearly": {
                "in": "february",
                "on": 29,
                "at": "noon"
            }
        }
    },
    input={
        "simple": {
            "payload": {
                "send": "yes"
            }
        }
    },
    condition={
        "always": {}
    },
    actions={
        "test_index": {
            "throttle_period": "15m",
            "index": {
                "index": "test"
            }
        }
    },
)
print(resp)

const response = await client.watcher.putWatch({
  id: "my_watch",
  trigger: {
    schedule: {
      yearly: {
        in: "february",
        on: 29,
        at: "noon",
      },
    },
  },
  input: {
    simple: {
      payload: {
        send: "yes",
      },
    },
  },
  condition: {
    always: {},
  },
  actions: {
    test_index: {
      throttle_period: "15m",
      index: {
        index: "test",
      },
    },
  },
});
console.log(response);

PUT _watcher/watch/my_watch
{
  "trigger" : {
    "schedule" : {
      "yearly" : { "in" : "february", "on" : 29, "at" : "noon" }
    }
  },
  "input": {
    "simple": {
      "payload": {
        "send": "yes"
      }
    }
  },
  "condition": {
    "always": {}
  },
  "actions": {
    "test_index": {
      "throttle_period": "15m",
      "index": {
        "index": "test"
      }
    }
  }
}

The current status of a watch and the state of its actions is returned with the watch definition when you call the Get Watch API:

resp = client.watcher.get_watch(
    id="my_watch",
)
print(resp)

const response = await client.watcher.getWatch({
  id: "my_watch",
});
console.log(response);

GET _watcher/watch/my_watch

The action state of a newly-created watch is awaits_successful_execution:

{
  "found": true,
  "_seq_no": 0,
  "_primary_term": 1,
  "_version": 1,
  "_id": "my_watch",
  "status": {
    "version": 1,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "awaits_successful_execution"
        }
      }
    },
    "state": ...
  },
  "watch": ...
}

When the watch executes and the condition matches, the value of the ack.state changes to ackable. Let’s force execution of the watch and fetch it again to check the status:

resp = client.watcher.execute_watch(
    id="my_watch",
    record_execution=True,
)
print(resp)

resp1 = client.watcher.get_watch(
    id="my_watch",
)
print(resp1)

const response = await client.watcher.executeWatch({
  id: "my_watch",
  record_execution: true,
});
console.log(response);

const response1 = await client.watcher.getWatch({
  id: "my_watch",
});
console.log(response1);

POST _watcher/watch/my_watch/_execute
{
  "record_execution" : true
}

GET _watcher/watch/my_watch

and the action is now in ackable state:

{
  "found": true,
  "_id": "my_watch",
  "_seq_no": 1,
  "_primary_term": 1,
  "_version": 2,
  "status": {
    "version": 2,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "ackable"
        },
        "last_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        },
        "last_successful_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        }
      }
    },
    "state": ...,
    "execution_state": "executed",
    "last_checked": ...,
    "last_met_condition": ...
  },
  "watch": ...
}

Now we can acknowledge it:

resp = client.watcher.ack_watch(
    watch_id="my_watch",
    action_id="test_index",
)
print(resp)

resp1 = client.watcher.get_watch(
    id="my_watch",
)
print(resp1)

const response = await client.watcher.ackWatch({
  watch_id: "my_watch",
  action_id: "test_index",
});
console.log(response);

const response1 = await client.watcher.getWatch({
  id: "my_watch",
});
console.log(response1);

PUT _watcher/watch/my_watch/_ack/test_index
GET _watcher/watch/my_watch

{
  "found": true,
  "_id": "my_watch",
  "_seq_no": 2,
  "_primary_term": 1,
  "_version": 3,
  "status": {
    "version": 3,
    "actions": {
      "test_index": {
        "ack": {
          "timestamp": "2015-05-26T18:04:27.723Z",
          "state": "acked"
        },
        "last_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        },
        "last_successful_execution" : {
          "timestamp": "2015-05-25T18:04:27.723Z",
          "successful": true
        }
      }
    },
    "state": ...,
    "execution_state": "executed",
    "last_checked": ...,
    "last_met_condition": ...
  },
  "watch": ...
}

Acknowledging an action throttles further executions of that action until its ack.state is reset to awaits_successful_execution. This happens when the condition of the watch is not met (the condition evaluates to false).

You can acknowledge multiple actions by assigning the actions parameter a comma-separated list of action ids:

resp = client.watcher.ack_watch(
    watch_id="my_watch",
    action_id="action1,action2",
)
print(resp)

const response = await client.watcher.ackWatch({
  watch_id: "my_watch",
  action_id: "action1,action2",
});
console.log(response);

POST _watcher/watch/my_watch/_ack/action1,action2

To acknowledge all of the actions of a watch, simply omit the actions parameter:

resp = client.watcher.ack_watch(
    watch_id="my_watch",
)
print(resp)

const response = await client.watcher.ackWatch({
  watch_id: "my_watch",
});
console.log(response);

POST _watcher/watch/my_watch/_ack

The response looks like a get watch response, but only contains the status:

{
  "status": {
    "state": {
      "active": true,
      "timestamp": "2015-05-26T18:04:27.723Z"
    },
    "last_checked": "2015-05-26T18:04:27.753Z",
    "last_met_condition": "2015-05-26T18:04:27.763Z",
    "actions": {
      "test_index": {
        "ack" : {
          "timestamp": "2015-05-26T18:04:27.713Z",
          "state": "acked"
        },
        "last_execution" : {
          "timestamp": "2015-05-25T18:04:27.733Z",
          "successful": true
        },
        "last_successful_execution" : {
          "timestamp": "2015-05-25T18:04:27.773Z",
          "successful": true
        }
      }
    },
    "execution_state": "executed",
    "version": 2
  }
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/watcher-api-ack-watch.html