Create a rule
https://{kibana_url}
- POST /api/alerting/v2/rules
- POST /s/{space_id}/api/alerting/v2/rules
Refer to Spaces for more information.
Creates a rule with a server-generated identifier. To create or replace a rule with a client-supplied identifier, use PUT /api/alerting/v2/rules/{id}/.
[Required authorization] Route required privileges: manage_alerting-v2-rules.
Request
-
artifactsobject · min: 1 · max: 100 -
Optional objects attached to the rule, such as a runbook or a dashboard. Each item has
id,type, anddata. The shape ofdatadepends ontype. For example, arunbookusescontentand adashboardusesdashboard_id. Known types are validated against that shape. Unknown types are stored whenid,type, anddataare present. An empty array is rejected: omitartifactson create, or sendnullon PATCH to clear. -
grouping -
Grouping configuration.
-
fieldsstring · min: 1 · max: 16required -
Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
-
kind -
Whether the rule creates alerts (
alert) or only stores matching events (signal). -
Values:
alertsignal -
metadata -
Rule metadata.
-
builderobject -
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send
nullon PATCH to clear it. -
typestring · min: 1 · max: 64required -
Rule builder type.
-
descriptionstring · min: 1 · max: 1024 -
Human-readable description of the rule. Omit to leave it unset; send
nullon PATCH to clear it. An empty string is rejected. -
namestring · min: 1 · max: 256required -
Rule name (must be unique within the space).
-
Routing tags that link alerts from this rule to action policies. An action policy applies when its
matcher.tagscontains at least one of these tags. Only allowed when kind is "alert". -
Tags for categorization, e.g. ["production", "infra"].
-
no_data -
What the rule does when a group has no data. Required when
kindisalert. Not allowed whenkindissignal. Any strategy other thanignorerequires eitherquery.breachorno_data.query, so that a group with no data can be told apart from one that stopped breaching. -
strategy -
Values:
ignore -
query -
ES|QL query the rule evaluates.
baseis required.breachis an optional clause appended to it. -
basestring · min: 1 · max: 10000required -
ES|QL query that specifies the data to evaluate. Must include a
FROMclause. Kibana applies the time filter fromschedule.lookbackusingtime_field. -
breach -
Optional ES|QL clause appended to
query.base. If omitted, every row fromquery.baseis a match, and ano_datastrategy other thanignorethen requiresno_data.query. -
segmentstring · min: 1 · max: 10000required -
ES|QL clause appended to
query.base, for exampleWHERE avg_cpu > 0.85. Don't include aFROMclause. -
recovery -
When an alert recovers. Required when
kindisalert. Not allowed whenkindissignal. -
strategy -
Values:
no_breach -
strategy -
Values:
manual -
schedule -
Execution schedule configuration.
-
state_transition -
Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes
activeorinactive. Allowed only whenkindisalert. -
pending -
countinteger · min: 0 · max: 1000 -
Consecutive matches the alert spends in
pendingbefore it becomesactiveon the next match. For example,2opens it on the third consecutive match. Set to0to open it on the first match. -
operator -
When both
countandtimeframeare set,andrequires both andorrequires either. Allowed only when both fields are present. -
Values:
andor -
timeframestring · max: 32 -
Duration the condition must hold, for example
5m. Combine withcountusingoperator. -
recovering -
countinteger · min: 0 · max: 1000 -
Consecutive recoveries the alert spends in
recoveringbefore it becomesinactiveon the next recovery. For example,2closes it on the third consecutive recovery. Set to0to close it on the first recovery. -
operator -
When both
countandtimeframeare set,andrequires both andorrequires either. Allowed only when both fields are present. -
Values:
andor -
timeframestring · max: 32 -
Duration the condition must hold, for example
5m. Combine withcountusingoperator. -
time_fieldstring · min: 1 · max: 256 · default: @timestamp -
Document field Kibana uses with
schedule.lookbackto time-filterquery.base.
strategy: ignore
Does not check whether a group still has data. Missing groups do not produce no_data events.
strategy: keep_last
Holds the alert's current status when the rule finds no data.
strategy: resolve
Closes the alert the first time the rule finds no data for a group.
strategy: alert
Marks an existing alert active when the rule finds no data. It never opens an alert for a group that has not breached. Not accepted when creating or updating rules.
strategy: no_breach
Recovers the alert when its group no longer appears in the breach results.
strategy: condition
Recovers the alert when query.base plus segment returns the group. Requires query.breach.
strategy: query
Recovers the alert when this separate query returns the group.
strategy: manual
Does not recover automatically. Close the alert with a user action. state_transition.recovering has no effect.
Responses
Returns the newly created rule.
-
artifactsobject · min: 1 · max: 100 -
Optional objects attached to the rule, such as a runbook or a dashboard. Each item has
id,type, anddata. The shape ofdatadepends ontype. For example, arunbookusescontentand adashboardusesdashboard_id. Known types are validated against that shape. Unknown types are stored whenid,type, anddataare present. An empty array is rejected: omitartifactson create, or sendnullon PATCH to clear. -
created_atstring · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$required -
ISO timestamp when the rule was created.
-
created_by -
Actor who created the rule.
-
profile_uidstringrequired nullable -
User profile ID of the actor, or
nullwhen it cannot be resolved. -
enabledbooleanrequired -
Whether the rule is enabled.
-
grouping -
Grouping configuration.
-
fieldsstring · min: 1 · max: 16required -
Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
-
idstringrequired -
Unique rule identifier.
-
kind -
Whether the rule creates alerts (
alert) or only stores matching events (signal). -
Values:
alertsignal -
metadata -
Rule metadata.
-
builderobject -
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send
nullon PATCH to clear it. -
typestring · min: 1 · max: 64required -
Rule builder type.
-
descriptionstring · min: 1 · max: 1024 -
Human-readable description of the rule. Omit to leave it unset; send
nullon PATCH to clear it. An empty string is rejected. -
namestring · min: 1 · max: 256required -
Rule name (must be unique within the space).
-
Routing tags that link alerts from this rule to action policies. An action policy applies when its
matcher.tagscontains at least one of these tags. Only allowed when kind is "alert". -
Tags for categorization, e.g. ["production", "infra"].
-
no_data -
What the rule does when a group has no data. Required when
kindisalert. Not allowed whenkindissignal. Any strategy other thanignorerequires eitherquery.breachorno_data.query, so that a group with no data can be told apart from one that stopped breaching. -
strategy -
Values:
ignore -
query -
ES|QL query the rule evaluates.
baseis required.breachis an optional clause appended to it. -
basestring · min: 1 · max: 10000required -
ES|QL query that specifies the data to evaluate. Must include a
FROMclause. Kibana applies the time filter fromschedule.lookbackusingtime_field. -
breach -
Optional ES|QL clause appended to
query.base. If omitted, every row fromquery.baseis a match, and ano_datastrategy other thanignorethen requiresno_data.query. -
segmentstring · min: 1 · max: 10000required -
ES|QL clause appended to
query.base, for exampleWHERE avg_cpu > 0.85. Don't include aFROMclause. -
recovery -
When an alert recovers. Required when
kindisalert. Not allowed whenkindissignal. -
strategy -
Values:
no_breach -
strategy -
Values:
manual -
schedule -
Execution schedule configuration.
-
state_transition -
Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes
activeorinactive. Allowed only whenkindisalert. -
pending -
countinteger · min: 0 · max: 1000 -
Consecutive matches the alert spends in
pendingbefore it becomesactiveon the next match. For example,2opens it on the third consecutive match. Set to0to open it on the first match. -
operator -
When both
countandtimeframeare set,andrequires both andorrequires either. Allowed only when both fields are present. -
Values:
andor -
timeframestring · max: 32 -
Duration the condition must hold, for example
5m. Combine withcountusingoperator. -
recovering -
countinteger · min: 0 · max: 1000 -
Consecutive recoveries the alert spends in
recoveringbefore it becomesinactiveon the next recovery. For example,2closes it on the third consecutive recovery. Set to0to close it on the first recovery. -
operator -
When both
countandtimeframeare set,andrequires both andorrequires either. Allowed only when both fields are present. -
Values:
andor -
timeframestring · max: 32 -
Duration the condition must hold, for example
5m. Combine withcountusingoperator. -
time_fieldstring · min: 1 · max: 256 · default: @timestamp -
Document field Kibana uses with
schedule.lookbackto time-filterquery.base. -
updated_atstring · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$required -
ISO timestamp when the rule was last updated.
-
updated_by -
Actor who last updated the rule.
-
profile_uidstringrequired nullable -
User profile ID of the actor, or
nullwhen it cannot be resolved. -
versioninteger · min: 1 · max: 9007199254740991required -
Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as
rule.version.
strategy: ignore
Does not check whether a group still has data. Missing groups do not produce no_data events.
strategy: keep_last
Holds the alert's current status when the rule finds no data.
strategy: resolve
Closes the alert the first time the rule finds no data for a group.
strategy: alert
Marks an existing alert active when the rule finds no data. It never opens an alert for a group that has not breached. Not accepted when creating or updating rules.
strategy: no_breach
Recovers the alert when its group no longer appears in the breach results.
strategy: condition
Recovers the alert when query.base plus segment returns the group. Requires query.breach.
strategy: query
Recovers the alert when this separate query returns the group.
strategy: manual
Does not recover automatically. Close the alert with a user action. state_transition.recovering has no effect.
Indicates an invalid schema or parameters.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the request was not authenticated.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the user does not have the required privileges to perform the request.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates an unexpected server-side error.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.
-
codestringrequired -
Stable error code you can branch on, for example
INVALID_SCHEDULEorRULE_ALREADY_EXISTS. -
detailsmap string to object -
Optional extra information about the error, for example field validation issues or the
rule_idwhen that ID already exists. -
errorstringrequired -
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
-
messagestringrequired -
A readable explanation of the error. The wording can change without notice. Do not parse this field.