AuthThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.AvailabilityExperimental since 9.5This functionality is experimental and is not ready for production usage. Experimental features may change or be removed at any time. Elastic will work to fix any issues, but experimental features are not subject to the support SLA of official GA features. Specific Support terms apply.Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present.
datamapstring to objectrequired
Structured artifact data.
idstring · min length: 1 · max length: 256required
Artifact identifier.
typestring · min length: 1 · max length: 128required
Artifact type.
created_atstringrequired
ISO timestamp when the rule was created.
created_bystringrequirednullable
User who created the rule.
enabledbooleanrequired
Whether the rule is enabled.
groupingobject
Grouping configuration.
fieldsstring[] · max items: 16required
Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
idstringrequired
Unique rule identifier.
kindenumrequired
Whether the rule creates alerts (alert) or only stores matching events (signal).
Values:alertsignal
metadataobjectrequired
builder_typestring · max length: 64
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.
descriptionstring · max length: 1024
Human-readable description of the rule.
namestring · min length: 1 · max length: 256required
Rule name (must be unique within the space).
ownerstring · max length: 256
Owner of the rule.
tagsstring[] · min items: 1 · max items: 20
Tags for categorization, e.g. ["production", "infra"].
Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.
no_data_strategyenum
How the rule behaves when it finds no data for a group. If you omit this field or set it to none, those runs are ignored. If you set last_known_status or recover, a standalone query (query.format: standalone) must include query.no_data. A composed query (query.format: composed) uses query.base to detect whether data is present. The emit value is not accepted when creating or updating rules.
Values:last_known_statusemitrecovernone
queryuniononeOfrequired
Detection query configuration.
One of:(determined by format)
format: composed
Composed query: a shared base with appendable breach and recovery segments.
formatenumrequired
Values:composed
basestring · min length: 1 · max length: 10000required
Base ES|QL query. Time filters are applied automatically via the lookback window.
breachobject
Breach detection configuration. Omit to treat every base row as a breach.
segmentstring · min length: 1 · max length: 10000required
A clause appended to the end of the rule's ES|QL query. Required in breach blocks.
recoveryobject
Recovery query segment. Required when recovery_strategy is "query".
segmentstring · min length: 1 · max length: 10000required
Appendable ES|QL segment for recovery detection.
format: standalone
Standalone queries: independent full queries for breach, recovery, and no_data.
formatenumrequired
Values:standalone
breachobjectrequired
Breach detection configuration (required).
querystring · min length: 1 · max length: 10000required
Full ES|QL query for breach detection (required).
no_dataobject
No-data detection query. Required when no_data_strategy is not "none".
querystring · min length: 1 · max length: 10000required
Full ES|QL query that detects presence of data.
recoveryobject
Recovery query. Required when recovery_strategy is "query".
querystring · min length: 1 · max length: 10000required
Full ES|QL query for recovery detection.
recovery_strategyenum
The condition that marks an alert recovered. If omitted or set to none, recovery is disabled: the alert stays active even after the breach query stops returning matches, and state_transition.recovering_count / recovering_timeframe are not allowed. Set to no_breach to recover when the breach query stops returning matches. Set to query only when you also provide query.recovery.
Values:no_breachquerynone
scheduleobjectrequired
Execution schedule configuration.
everystring · max length: 32required
Execution interval, e.g. 1m, 5m, 1h.
lookbackstring · max length: 32
Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.
state_transitionobjectnullable
Consecutive-match or time requirements before an alert becomes active or inactive. Applies only when kind is alert.
pending_countinteger · min: 0 · max: 1000
Number of consecutive matches required before the alert becomes active.
pending_operatorenum
The operator that combines pending_count and pending_timeframe. AND requires both. OR requires either.
Values:ANDOR
pending_timeframestring · max length: 32
Time window used with pending_count, for example 5m or 15m.
recovering_countinteger · min: 0 · max: 1000
Number of consecutive recoveries required before the alert becomes inactive.
recovering_operatorenum
The operator that combines recovering_count and recovering_timeframe. AND requires both. OR requires either.
Values:ANDOR
recovering_timeframestring · max length: 32
Time window used with recovering_count, for example 5m or 15m.
time_fieldstring · min length: 1 · max length: 128 · default: @timestamp
Document field used as the event time when applying the lookback window. Defaults to @timestamp.
updated_atstringrequired
ISO timestamp when the rule was last updated.
updated_bystringrequirednullable
User who last updated the rule.
versionstring
The saved object version token of the rule, used for optimistic concurrency control.
Indicates the request failed schema validation.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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 a rule with the given ID does not exist.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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 rule was concurrently updated by another caller.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional extra information about the error, for example field validation issues or the rule_id when 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.