Path parameters
-
id
string Required The identifier for the rule. If it is omitted, an ID is randomly generated.
Body
-
actions
array[object] An action that runs under defined conditions.
Default value is
[]
(empty). -
alert_delay
object Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.
Additional properties are NOT allowed.
-
consumer
string Required The name of the application or feature that owns the rule. For example:
alerts
,apm
,discover
,infrastructure
,logs
,metrics
,ml
,monitoring
,securitySolution
,siem
,stackAlerts
, oruptime
. -
enabled
boolean Indicates whether you want to run the rule on an interval basis after it is created.
Default value is
true
. -
flapping
object | null When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.
Additional properties are NOT allowed.
-
name
string Required The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
-
notify_when
string | null Indicates how often alerts generate actions. Valid values include:
onActionGroupChange
: Actions run when the alert status changes;onActiveAlert
: Actions run when the alert becomes active and at each check interval while the rule conditions are met;onThrottleInterval
: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specifynotify_when
at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.Values are
onActionGroupChange
,onActiveAlert
, oronThrottleInterval
. -
rule_type_id
string Required The rule type identifier.
-
schedule
object Required The check interval, which specifies how frequently the rule conditions are checked.
Additional properties are NOT allowed.
-
throttle
string | null Use the
throttle
property in the actionfrequency
object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values. params
object The parameters for the rule.
Any of: params_property_apm_anomalyobject params_property_apm_error_countobject params_property_apm_transaction_durationobject params_property_apm_transaction_error_rateobject params_es_query_dsl_ruleobject params_es_query_esql_ruleobject params_es_query_kql_ruleobject params_index_threshold_ruleobject params_property_infra_inventoryobject Countobject Ratioobject params_property_infra_metric_thresholdobject params_property_slo_burn_rateobject params_property_synthetics_uptime_tlsobject params_property_synthetics_monitor_statusobject
curl \
--request POST http://localhost:5622/api/alerting/rule/{id} \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"name":"my Elasticsearch query ESQL rule","params":{"size":0,"esqlQuery":{"esql":"FROM kibana_sample_data_logs | KEEP bytes, clientip, host, geo.dest | where geo.dest != \"GB\" | STATS sumbytes = sum(bytes) by clientip, host | WHERE sumbytes \u003e 5000 | SORT sumbytes desc | LIMIT 10"},"threshold":[0],"timeField":"@timestamp","searchType":"esqlQuery","timeWindowSize":1,"timeWindowUnit":"d","thresholdComparator":"\u003e"},"actions":[{"id":"d0db1fe0-78d6-11ee-9177-f7d404c8c945","group":"query matched","params":{"level":"info","message":"Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"},"frequency":{"summary":false,"notify_when":"onActiveAlert"}}],"consumer":"stackAlerts","schedule":{"interval":"1d"},"rule_type_id":".es-query"}'
{
"name": "my Elasticsearch query ESQL rule",
"params": {
"size": 0,
"esqlQuery": {
"esql": "FROM kibana_sample_data_logs | KEEP bytes, clientip, host, geo.dest | where geo.dest != \"GB\" | STATS sumbytes = sum(bytes) by clientip, host | WHERE sumbytes > 5000 | SORT sumbytes desc | LIMIT 10"
},
"threshold": [
0
],
"timeField": "@timestamp",
"searchType": "esqlQuery",
"timeWindowSize": 1,
"timeWindowUnit": "d",
"thresholdComparator": ">"
},
"actions": [
{
"id": "d0db1fe0-78d6-11ee-9177-f7d404c8c945",
"group": "query matched",
"params": {
"level": "info",
"message": "Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"
},
"frequency": {
"summary": false,
"notify_when": "onActiveAlert"
}
}
],
"consumer": "stackAlerts",
"schedule": {
"interval": "1d"
},
"rule_type_id": ".es-query"
}
{
"name": "my Elasticsearch query KQL rule",
"params": {
"size": 100,
"aggType": "count",
"groupBy": "all",
"threshold": [
1000
],
"searchType": "searchSource",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"searchConfiguration": {
"index": "90943e30-9a47-11e8-b64d-95841ca0b247",
"query": {
"query": "\"\"geo.src : \"US\" \"\"",
"language": "kuery"
}
},
"thresholdComparator": ">",
"excludeHitsFromPreviousRun": true
},
"consumer": "alerts",
"schedule": {
"interval": "1m"
},
"rule_type_id": ".es-query"
}
{
"name": "my Elasticsearch query rule",
"params": {
"size": 100,
"index": [
"kibana_sample_data_logs"
],
"esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
"threshold": [
100
],
"timeField": "@timestamp",
"timeWindowSize": 1,
"timeWindowUnit": "d",
"thresholdComparator": ">"
},
"actions": [
{
"id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
"group": "query matched",
"params": {
"level": "info",
"message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
},
"frequency": {
"summary": true,
"throttle": "1d",
"notify_when": "onThrottleInterval"
}
},
{
"id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
"group": "recovered",
"params": {
"level": "info",
"message": "Recovered"
},
"frequency": {
"summary": false,
"notify_when": "onActionGroupChange"
}
}
],
"consumer": "alerts",
"schedule": {
"interval": "1d"
},
"rule_type_id": ".es-query"
}
{
"name": "my rule",
"tags": [
"cpu"
],
"params": {
"index": [
".test-index"
],
"aggType": "avg",
"groupBy": "top",
"aggField": "sheet.version",
"termSize": 6,
"termField": "name.keyword",
"threshold": [
1000
],
"timeField": "@timestamp",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"thresholdComparator": ">"
},
"actions": [
{
"id": "48de3460-f401-11ed-9f8e-399c75a2deeb",
"group": "threshold met",
"params": {
"level": "info",
"message": "Rule '{{rule.name}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
},
"frequency": {
"summary": false,
"notify_when": "onActionGroupChange"
}
}
],
"consumer": "alerts",
"schedule": {
"interval": "1m"
},
"alert_delay": {
"active": 3
},
"rule_type_id": ".index-threshold"
}
{
"name": "my tracking rule",
"params": {
"index": "kibana_sample_data_logs",
"entity": "agent.keyword",
"indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
"geoField": "geo.coordinates",
"dateField\"": "@timestamp",
"boundaryType": "entireIndex",
"boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc",
"boundaryGeoField": "location",
"boundaryNameField": "name",
"boundaryIndexTitle": "boundary*"
},
"consumer": "alerts",
"schedule": {
"interval": "1h"
},
"rule_type_id": ".geo-containment"
}
{
"id": "e0d62360-78e8-11ee-9177-f7d404c8c945",
"name": "my Elasticsearch query ESQL rule",
"tags": [],
"params": {
"size": 0,
"aggType": "count",
"groupBy": "all",
"esqlQuery": {
"esql": "FROM kibana_sample_data_logs | keep bytes, clientip, host, geo.dest | WHERE geo.dest != \"GB\" | stats sumbytes = sum(bytes) by clientip, host | WHERE sumbytes > 5000 | sort sumbytes desc | limit 10"
},
"threshold": [
0
],
"timeField": "@timestamp",
"searchType": "esqlQuery",
"timeWindowSize": 1,
"timeWindowUnit": "d",
"thresholdComparator": ">",
"excludeHitsFromPreviousRun\"": "true,"
},
"actions": [
{
"id": "d0db1fe0-78d6-11ee-9177-f7d404c8c945",
"uuid": "bfe370a3-531b-4855-bbe6-ad739f578844",
"group": "query matched",
"params": {
"level": "info",
"message": "Elasticsearch query rule '{{rule.name}}' is active:\n- Value: {{context.value}} - Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}} - Timestamp: {{context.date}} - Link: {{context.link}}"
},
"frequency": {
"summary": false,
"throttle": null,
"notify_when": "onActiveAlert"
},
"connector_type_id": ".server-log"
}
],
"enabled": true,
"running": false,
"consumer": "stackAlerts",
"mute_all": false,
"revision": 0,
"schedule": {
"interval": "1d"
},
"throttle": null,
"created_at": "2023-11-01T19:00:10.453Z",
"created_by": "elastic",
"updated_at": "2023-11-01T19:00:10.453Z",
"updated_by": "elastic\",",
"notify_when": null,
"rule_type_id": ".es-query",
"api_key_owner": "elastic",
"muted_alert_ids": [],
"execution_status": {
"status": "pending",
"last_execution_date": "2023-11-01T19:00:10.453Z"
},
"scheduled_task_id": "e0d62360-78e8-11ee-9177-f7d404c8c945",
"api_key_created_by_user": false
}
{
"id": "7bd506d0-2284-11ee-8fad-6101956ced88",
"name": "my Elasticsearch query KQL rule\"",
"tags": [],
"params": {
"size": 100,
"aggType": "count",
"groupBy": "all",
"threshold": [
1000
],
"searchType": "searchSource",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"searchConfiguration": {
"index": "90943e30-9a47-11e8-b64d-95841ca0b247",
"query": {
"query": "\"\"geo.src : \"US\" \"\"",
"language": "kuery"
}
},
"thresholdComparator": ">",
"excludeHitsFromPreviousRun": true
},
"actions": [],
"enabled": true,
"running": false,
"consumer": "alerts",
"mute_all": false,
"revision": 0,
"schedule": {
"interval": "1m"
},
"throttle": null,
"created_at": "2023-07-14T20:24:50.729Z",
"created_by": "elastic",
"updated_at": "2023-07-14T20:24:50.729Z",
"updated_by": "elastic",
"notify_when": null,
"rule_type_id": ".es-query",
"api_key_owner": "elastic",
"muted_alert_ids": [],
"execution_status": {
"status": "pending",
"last_execution_date": "2023-07-14T20:24:50.729Z"
},
"scheduled_task_id": "7bd506d0-2284-11ee-8fad-6101956ced88",
"api_key_created_by_user": false
}
{
"id": "58148c70-407f-11ee-850e-c71febc4ca7f",
"name": "my Elasticsearch query rule",
"tags": [],
"params": {
"size": 100,
"index": [
"kibana_sample_data_logs"
],
"aggType": "count",
"esQuery": "\"\"\"{\"query\":{\"match_all\" : {}}}\"\"\"",
"groupBy": "all",
"threshold": [
100
],
"timeField": "@timestamp",
"searchType": "esQuery",
"timeWindowSize": 1,
"timeWindowUnit": "d",
"thresholdComparator": ">",
"excludeHitsFromPreviousRun": true
},
"actions": [
{
"id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
"uuid": "53f3c2a3-e5d0-4cfa-af3b-6f0881385e78",
"group": "query matched",
"params": {
"level": "info",
"message": "The system has detected {{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, and {{alerts.recovered.count}} recovered alerts."
},
"frequency": {
"summary": true,
"throttle": "1d",
"notify_when": "onThrottleInterval"
},
"connector_type_id": ".server-log"
},
{
"id": "fdbece50-406c-11ee-850e-c71febc4ca7f",
"uuid": "2324e45b-c0df-45c7-9d70-4993e30be758",
"group": "recovered",
"params": {
"level": "info",
"message": "Recovered"
},
"frequency": {
"summary": false,
"throttle": null,
"notify_when": "onActionGroupChange"
},
"connector_type_id": ".server-log"
}
],
"enabled": true,
"running": false,
"consumer": "alerts",
"mute_all": false,
"revision": 0,
"schedule": {
"interval": "1d"
},
"throttle": null,
"created_at": "2023-08-22T00:03:38.263Z",
"created_by": "elastic",
"updated_at": "2023-08-22T00:03:38.263Z",
"updated_by": "elastic",
"notify_when": null,
"rule_type_id": ".es-query",
"api_key_owner": "elastic",
"muted_alert_ids": [],
"execution_status": {
"status": "pending",
"last_execution_date": "2023-08-22T00:03:38.263Z"
},
"scheduled_task_id": "58148c70-407f-11ee-850e-c71febc4ca7f",
"api_key_created_by_user": false
}
{
"id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
"name": "my rule",
"tags": [
"cpu"
],
"params": {
"index": [
".test-index"
],
"aggType": "avg",
"groupBy": "top",
"aggField": "sheet.version",
"termSize": 6,
"termField": "name.keyword",
"threshold": [
1000
],
"timeField": "@timestamp",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"thresholdComparator": ">"
},
"actions": [
{
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
"uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
"group": "threshold met",
"params": {
"level": "info",
"message": "Rule {{rule.name}} is active for group {{context.group} :\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
},
"frequency": {
"summary": false,
"throttle": null,
"notify_when": "onActionGroupChange"
},
"connector_type_id": ".server-log"
}
],
"enabled": true,
"running": false,
"consumer": "alerts",
"mute_all": false,
"revision": 0,
"schedule": {
"interval": "1m"
},
"throttle": null,
"created_at": "2022-06-08T17:20:31.632Z",
"created_by": "elastic",
"updated_at": "2022-06-08T17:20:31.632Z",
"updated_by": "elastic",
"alert_delay": {
"active": 3
},
"notify_when": null,
"rule_type_id": ".index-threshold",
"api_key_owner": "elastic",
"muted_alert_ids": [],
"execution_status": {
"status": "pending",
"last_execution_date": "2022-06-08T17:20:31.632Z"
},
"scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
"api_key_created_by_user": false
}
{
"id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
"name": "my tracking rule",
"tags": [],
"params": {
"index": "kibana_sample_data_logs",
"entity": "agent.keyword",
"indexId": "90943e30-9a47-11e8-b64d-95841ca0b247",
"geoField": "geo.coordinates",
"dateField": "@timestamp",
"boundaryType": "entireIndex",
"boundaryIndexId": "0cd90abf-abe7-44c7-909a-f621bbbcfefc",
"boundaryGeoField": "location",
"boundaryNameField": "name",
"boundaryIndexTitle": "boundary*"
},
"actions": [],
"enabled": true,
"running": false,
"consumer": "alerts",
"last_run": {
"outcome": "succeeded",
"warning": null,
"outcome_msg": null,
"alerts_count": {
"new": 0,
"active": 0,
"ignored": 0,
"recovered": 0
},
"outcome_order": 0
},
"mute_all": false,
"next_run": "2024-02-15T03:26:38.033Z",
"revision": 1,
"schedule": {
"interval": "1h"
},
"throttle": null,
"created_at": "2024-02-14T19:52:55.920Z",
"created_by": "elastic",
"updated_at": "2024-02-15T03:24:32.574Z",
"updated_by": "elastic",
"notify_when": null,
"rule_type_id": ".geo-containment",
"api_key_owner": "elastic",
"muted_alert_ids": [],
"execution_status": {
"status": "ok",
"last_duration": 74,
"last_execution_date": "2024-02-15T03:25:38.125Z"
},
"scheduled_task_id": "b6883f9d-5f70-4758-a66e-369d7c26012f",
"api_key_created_by_user": false
}