List rules
https://{kibana_url}
- GET /api/alerting/v2/rules
[Required authorization] Route required privileges: read_alerting-v2-rules.
Query Parameters
-
pageinteger · min: 1 · max: 10000 The page number to return. Defaults to 1.
page * per_pagecannot exceed 10000.-
per_pageinteger · min: 1 · max: 1000 The number of rules to return per page. Defaults to 20.
-
filterstring · max: 4096 The filter to apply to the rules.
-
searchstring · min: 1 · max: 256 A text string to search across rule fields.
Responses
Returns a paginated list of rules.
-
itemsobjectrequired -
The list of rules.
-
artifactsobject · 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. -
created_atstringrequired -
ISO timestamp when the rule was created.
-
created_bystringrequired nullable -
User who created the rule.
-
enabledbooleanrequired -
Whether the rule is enabled.
-
grouping -
Grouping configuration.
-
fieldsstring · 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 -
builder_typestring · max: 64 -
Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.
-
descriptionstring · max: 1024 -
Human-readable description of the rule.
-
namestring · min: 1 · max: 256required -
Rule name (must be unique within the space).
-
ownerstring · max: 256 -
Owner of the rule.
-
Tags for categorization, e.g. ["production", "infra"].
-
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. -
no_data_strategy -
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 setlast_known_statusorrecover, a standalone query (query.format: standalone) must includequery.no_data. A composed query (query.format: composed) usesquery.baseto detect whether data is present. Theemitvalue is not accepted when creating or updating rules. -
Values:
last_known_statusemitrecovernone -
query -
Detection query configuration.
-
basestring · min: 1 · max: 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: 1 · max: 10000required -
A clause appended to the end of the rule's ES|QL query. Required in breach blocks.
-
format -
Values:
composed -
recovery_strategy -
The condition that marks an alert recovered. If omitted or set to
none, recovery is disabled: the alert staysactiveeven after the breach query stops returning matches, andstate_transition.recovering_count/recovering_timeframeare not allowed. Set tono_breachto recover when the breach query stops returning matches. Set toqueryonly when you also providequery.recovery. -
Values:
no_breachquerynone -
schedule -
Execution schedule configuration.
-
state_transitionobjectnullable -
Consecutive-match or time requirements before an alert becomes
activeorinactive. Applies only whenkindisalert. -
pending_countinteger · min: 0 · max: 1000 -
Number of consecutive matches required before the alert becomes
active. -
pending_operator -
The operator that combines
pending_countandpending_timeframe.ANDrequires both.ORrequires either. -
Values:
ANDOR -
pending_timeframestring · max: 32 -
Time window used with
pending_count, for example5mor15m. -
recovering_countinteger · min: 0 · max: 1000 -
Number of consecutive recoveries required before the alert becomes
inactive. -
recovering_operator -
The operator that combines
recovering_countandrecovering_timeframe.ANDrequires both.ORrequires either. -
Values:
ANDOR -
recovering_timeframestring · max: 32 -
Time window used with
recovering_count, for example5mor15m. -
time_fieldstring · min: 1 · max: 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_bystringrequired nullable -
User who last updated the rule.
-
versionstring -
The saved object version token of the rule, used for optimistic concurrency control.
-
pagenumberrequired -
The current page number.
-
per_pagenumberrequired -
The number of rules per page.
-
totalnumberrequired -
The total number of rules matching the query.
format: composed
Composed query: a shared base with appendable breach and recovery segments.
format: standalone
Standalone queries: independent full queries for breach, recovery, and no_data.
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.