Kibana Alerting Rules
Core Concepts
A rule has three parts: conditions (what to detect), schedule (how often to check), and actions (what
happens when conditions are met). When conditions are met, the rule creates alerts, which trigger actions via
connectors.
Authentication
All alerting API calls require either API key auth or Basic auth. Every mutating request must include the kbn-xsrf
header.
Required Privileges
all privileges for the appropriate Kibana feature (e.g., Stack Rules, Observability, Security)read privileges for Actions and Connectors (to attach actions to rules)
API Reference
Base path: <kibana_url>/api/alerting (or /s/<space_id>/api/alerting for non-default spaces).
| Operation |
Method |
Endpoint |
| Create rule |
POST |
/api/alerting/rule/{id} |
| Update rule |
PUT |
/api/alerting/rule/{id} |
| Get rule |
GET |
/api/alerting/rule/{id} |
| Delete rule |
DELETE |
/api/alerting/rule/{id} |
| Find rules |
GET |
/api/alerting/rules/_find |
| List rule types |
GET |
/api/alerting/rule_types |
| Enable rule |
POST |
/api/alerting/rule/{id}/_enable |
| Disable rule |
POST |
/api/alerting/rule/{id}/_disable |
| Mute all alerts |
POST |
/api/alerting/rule/{id}/_mute_all |
| Unmute all alerts |
POST |
/api/alerting/rule/{id}/_unmute_all |
| Mute alert |
POST |
/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute |
| Unmute alert |
POST |
/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute |
| Update API key |
POST |
/api/alerting/rule/{id}/_update_api_key |
| Create snooze |
POST |
/api/alerting/rule/{id}/snooze_schedule |
| Delete snooze |
DELETE |
/api/alerting/rule/{ruleId}/snooze_schedule/{scheduleId} |
| Health check |
GET |
/api/alerting/_health |
Creating a Rule
Required Fields
| Field |
Type |
Description |
name |
string |
Display name (does not need to be unique) |
rule_type_id |
string |
The rule type (e.g., .es-query, .index-threshold) |
consumer |
string |
Owning app: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, uptime |
params |
object |
Rule-type-specific parameters |
schedule |
object |
Check interval, e.g., {"interval": "5m"} |
Optional Fields
| Field |
Type |
Description |
actions |
array |
Actions to run when conditions are met (each references a connector) |
tags |
array |
Tags for organizing rules |
enabled |
boolean |
Whether the rule runs immediately (default: true) |
notify_when |
string |
onActionGroupChange, onActiveAlert, or onThrottleInterval (prefer setting per-action instead) |
alert_delay |
object |
Alert only after N consecutive matches, e.g., {"active": 3} |
flapping |
object/null |
Override flapping detection settings |
Example: Create an Elasticsearch Query Rule
curl -X POST "https://my-kibana:5601/api/alerting/rule/my-rule-id" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-H "Authorization: ApiKey <your-api-key>" \
-d '{
"name": "High error rate",
"rule_type_id": ".es-query",
"consumer": "stackAlerts",
"schedule": { "interval": "5m" },
"params": {
"index": ["logs-*"],
"timeField": "@timestamp",
"esQuery": "{\"query\":{\"match\":{\"log.level\":\"error\"}}}",
"threshold": [100],
"thresholdComparator": ">",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"size": 100
},
"actions": [
{
"id": "my-slack-connector-id",
"group": "query matched",
"params": {
"message": "Alert: {{rule.name}} - {{context.hits}} hits detected"
},
"frequency": {
"summary": false,
"notify_when": "onActionGroupChange"
}
}
],
"tags": ["production", "errors"]
}'
The same structure applies to other rule types — set the appropriate rule_type_id (e.g., .index-threshold,
.es-query) and provide the matching params object. Use GET /api/alerting/rule_types to discover params schemas.
Updating a Rule
PUT /api/alerting/rule/{id} — send the complete rule body. rule_type_id and consumer are immutable after creation.
Returns 409 Conflict if another user updated the rule concurrently; re-fetch and retry.
Finding Rules
curl -X GET "https://my-kibana:5601/api/alerting/rules/_find?per_page=20&page=1&search=cpu&sort_field=name&sort_order=asc" \
-H "Authorization: ApiKey <your-api-key>"
Query parameters: per_page, page, search, default_search_operator, search_fields, sort_field, sort_order,
has_reference, fields, filter, filter_consumers.
Use the filter parameter with KQL syntax for advanced queries:
filter=alert.attributes.tags:"production"
Lifecycle Operations
curl -X POST ".../api/alerting/rule/{id}/_enable" -H "kbn-xsrf: true"
curl -X POST ".../api/alerting/rule/{id}/_disable" -H "kbn-xsrf: true"
curl -X POST ".../api/alerting/rule/{id}/_mute_all" -H "kbn-xsrf: true"
curl -X POST ".../api/alerting/rule/{rule_id}/alert/{alert_id}/_mute" -H "kbn-xsrf: true"
curl -X DELETE ".../api/alerting/rule/{id}" -H "kbn-xsrf: true"
Terraform Provider
Use the elasticstack provider resource elasticstack_kibana_alerting_rule.
terraform {
required_providers {
elasticstack = {
source = "elastic/elasticstack"
}
}
}
provider "elasticstack" {
kibana {
endpoints = ["https://my-kibana:5601"]
api_key = var.kibana_api_key
}
}
resource "elasticstack_kibana_alerting_rule" "cpu_alert" {
name = "CPU usage critical"
consumer = "stackAlerts"
rule_type_id = ".index-threshold"
interval = "1m"
enabled = true
params = jsonencode({
index = ["metrics-*"]
timeField = "@timestamp"
aggType = "avg"
aggField = "system.cpu.total.pct"
groupBy = "top"
termField = "host.name"
termSize = 10
threshold = [0.9]
thresholdComparator = ">"
timeWindowSize = 5
timeWindowUnit = "m"
})
tags = ["infrastructure", "production"]
}
Key Terraform notes:
params must be passed as a JSON-encoded string via jsonencode()- Use
elasticstack_kibana_action_connector data source or resource to reference connector IDs in actions
- Import existing rules:
terraform import elasticstack_kibana_alerting_rule.my_rule <space_id>/<rule_id> (use
default for the default space)
Triggering Kibana Workflows from Rules
Preview feature — available from Elastic Stack 9.3 and Elastic Cloud Serverless. APIs may change.
Attach a workflow as a rule action using the workflow ID as the connector ID. Set params: {} — alert context flows
automatically through the event object inside the workflow.
curl -X PUT "https://my-kibana:5601/api/alerting/rule/my-rule-id" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-H "Authorization: ApiKey <your-api-key>" \
-d '{
"name": "High error rate",
"schedule": { "interval": "5m" },
"params": { ... },
"actions": [
{
"id": "<workflow-id>",
"group": "query matched",
"params": {},
"frequency": { "summary": false, "notify_when": "onActionGroupChange" }
}
]
}'
In the UI: Stack Management > Rules > Actions > Workflows. Only enabled: true workflows appear in the picker.
For workflow YAML structure, {{ event }} context fields, step types, and patterns, refer to the kibana-connectors
skill if available.
Connectors and Actions in Rules
Each action references a connector by ID, an action group, action params (using Mustache templates), and a
per-action frequency object. Key fields:
group — which trigger state fires this action (e.g., "query matched", "Recovered"). Discover valid groups via
GET /api/alerting/rule_types.frequency.summary — true for a digest of all alerts; false for per-alert.frequency.notify_when — onActionGroupChange | onActiveAlert | onThrottleInterval.frequency.throttle — minimum repeat interval (e.g., "10m"); only applies with onThrottleInterval.
For full reference on action structure, Mustache variables ({{rule.name}}, {{context.*}}, {{alerts.new.count}}),
Mustache lambdas (EvalMath, FormatDate, ParseHjson), recovery actions, and multi-channel patterns, refer to the
kibana-connectors skill if available.
Best Practices
-
Set action frequency per action, not per rule. The notify_when field at the rule level is deprecated in favor
of per-action frequency objects. If you set it at the rule level and later edit the rule in the Kibana UI, it is
automatically converted to action-level values.
-
Use alert summaries to reduce notification noise. Instead of sending one notification per alert, configure
actions to send periodic summaries at a custom interval. Use "summary": true and set a throttle interval. This is
especially valuable for rules that monitor many hosts or documents.
-
Choose the right action frequency for each channel. Use onActionGroupChange for paging/ticketing systems (fire
once, resolve once). Use onActiveAlert for audit logging to an Index connector. Use onThrottleInterval with a
throttle like "30m" for dashboards or lower-priority notifications.
-
Always add a recovery action. Rules without a recovery action leave
