AuthThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.AvailabilityPlannedWe plan to add this functionality in a future Elastic Stack update. Subject to changes.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.
The page number to return. Defaults to 1. page * per_page cannot exceed 10000.
per_pageinteger · min: 1 · max: 100
The number of rules to return per page. Defaults to 20.
filterstring · min length: 1 · max length: 4096
A KQL filter to apply to the rules. Supported fields: id, kind, enabled, metadata.name, metadata.description, metadata.tags, metadata.routing_tags. Cannot be empty. Omit it to list every rule.
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. An empty array is rejected: omit artifacts on create, or send null on PATCH to clear.
datamapstring to objectrequired
Structured artifact data.
idstring · min length: 1 · max length: 150required
Artifact identifier.
typestring · min length: 1 · max length: 128required
Artifact type.
created_atstring · format: date-time · max length: 64required
ISO timestamp when the rule was created.
created_byobjectrequired
Actor who created the rule.
profile_uidstringrequirednullable
User profile ID of the actor, or null when it cannot be resolved.
enabledbooleanrequired
Whether the rule is enabled.
groupingobject
Grouping configuration.
fieldsstring[] · min items: 1 · 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
Rule metadata.
builderobject
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL; send null on PATCH to clear it.
typestring · min length: 1 · max length: 64required
Rule builder type.
descriptionstring · min length: 1 · max length: 1024
Human-readable description of the rule. Omit to leave it unset; send null on PATCH to clear it. An empty string is rejected.
namestring · min length: 1 · max length: 256required
Rule name.
routing_tagsstring[] · min items: 1 · max items: 20
Routing tags that link alerts from this rule to action policies. An action policy applies when its matcher.tags contains at least one of these tags. Only allowed when kind is "alert".
tagsstring[] · min items: 1 · max items: 20
Tags for categorization, e.g. ["production", "infra"].
no_datauniononeOf
What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.
One of:(determined by strategy)
strategy: ignore
Does not check whether a group still has data. Missing groups do not produce no_data events.
strategyenumrequired
Values:ignore
strategy: keep_last
Holds the alert's current status when the rule finds no data.
strategyenumrequired
Values:keep_last
querystring · min length: 1 · max length: 10000
Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
strategy: resolve
Closes the alert the first time the rule finds no data for a group.
strategyenumrequired
Values:resolve
querystring · min length: 1 · max length: 10000
Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
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.
strategyenumrequired
Values:alert
querystring · min length: 1 · max length: 10000
Optional ES|QL query that checks whether a group has data. If omitted, query.base is used, which then has to be a presence query in its own right — so query.breach is required.
queryobjectrequired
ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
basestring · min length: 1 · max length: 10000required
ES|QL query that specifies the data to evaluate. Must include a FROM clause. Kibana applies the time filter from schedule.lookback using time_field.
breachobject
Optional ES|QL clause appended to query.base. If omitted, every row from query.base is a match, and a no_data strategy other than ignore then requires no_data.query.
segmentstring · min length: 1 · max length: 10000required
ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.
recoveryuniononeOf
When an alert recovers. Required when kind is alert. Not allowed when kind is signal.
One of:(determined by strategy)
strategy: no_breach
Recovers the alert when its group no longer appears in the breach results.
strategyenumrequired
Values:no_breach
strategy: condition
Recovers the alert when query.base plus segment returns the group. Requires query.breach.
strategyenumrequired
Values:condition
segmentstring · min length: 1 · max length: 10000required
ES|QL clause appended to query.base, for example WHERE avg_cpu < 0.60. Don't include a FROM clause.
strategy: query
Recovers the alert when this separate query returns the group.
strategyenumrequired
Values:query
querystring · min length: 1 · max length: 10000required
Independent ES|QL query, including its own FROM clause. A matching group recovers the alert.
strategy: manual
Does not recover automatically. Close the alert with a user action. state_transition.recovering has no effect.
strategyenumrequired
Values:manual
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_transitionobject
Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.
pendingobject
countinteger · min: 0 · max: 1000
Consecutive matches the alert spends in pending before it becomes active on the next match. For example, 2 opens it on the third consecutive match. Set to 0 to open it on the first match.
operatorenum
When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
Values:andor
timeframestring · max length: 32
Duration the condition must hold, for example 5m. Combine with count using operator.
recoveringobject
countinteger · min: 0 · max: 1000
Consecutive recoveries the alert spends in recovering before it becomes inactive on the next recovery. For example, 2 closes it on the third consecutive recovery. Set to 0 to close it on the first recovery.
operatorenum
When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
Values:andor
timeframestring · max length: 32
Duration the condition must hold, for example 5m. Combine with count using operator.
time_fieldstring · min length: 1 · max length: 256 · default: @timestamp
Document field Kibana uses with schedule.lookback to time-filter query.base.
updated_atstring · format: date-time · max length: 64required
ISO timestamp when the rule was last updated.
updated_byobjectrequired
Actor who last updated the rule.
profile_uidstringrequirednullable
User profile ID of the actor, or null when it cannot be resolved.
Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.
pagenumberrequired
The current page number.
per_pagenumberrequired
The number of rules per page.
totalnumberrequired
The number of rules matching the query. This count is an estimate: results above 10,000 may be reported as 10,000.
Indicates an invalid schema or parameters.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
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.