Type to search.

Update a rule

Base URL
https://{kibana_url}
  • PATCH /api/alerting/v2/rules/{id}
Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Experimental since 9.5 This 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.

Required privileges

Privileges manage_alerting-v2-rules

Path parameters

id string · min length: 1 · max length: 150 required

The identifier for the rule.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

no_data_strategy enum

How the rule behaves when it finds no data for a group. If omitted, the existing value is kept. Set to null to clear it (those runs are then 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_status emit recover none
query union oneOf

Detection query configuration.

One of: (determined by format)
format: composed

Composed query: a shared base with appendable breach and recovery segments.

format enum required
Values: composed
base string · min length: 1 · max length: 10000 required

Base ES|QL query. Time filters are applied automatically via the lookback window.

recovery_strategy enum

The condition that marks an alert recovered. If omitted, the existing value is kept. Set to null to clear it (recovery is then disabled). Set to no_breach to recover when the breach query stops returning matches. Set to query only when you also provide query.recovery. With none, the alert stays active, even after the breach query stops returning matches. state_transition.recovering_count and recovering_timeframe require an explicit recovery_strategy other than none.

Values: no_breach query none
state_transition union anyOf
Any of:

Consecutive-match or time requirements before an alert becomes active or inactive. Applies only when kind is alert.

pending_count integer · min: 0 · max: 1000

Number of consecutive matches required before the alert becomes active.

pending_operator enum

The operator that combines pending_count and pending_timeframe. AND requires both. OR requires either.

Values: AND OR
pending_timeframe string · max length: 32

Time window used with pending_count, for example 5m or 15m.

recovering_count integer · min: 0 · max: 1000

Number of consecutive recoveries required before the alert becomes inactive.

recovering_operator enum

The operator that combines recovering_count and recovering_timeframe. AND requires both. OR requires either.

Values: AND OR
recovering_timeframe string · max length: 32

Time window used with recovering_count, for example 5m or 15m.

time_field string · min length: 1 · max length: 128

Document field used as the event time when applying the lookback window. If omitted, the existing value is kept.

version string · min length: 1 · max length: 256

The current version of the rule, used for optimistic concurrency control.

Responses

Returns the updated rule.

application/json
created_at string required

ISO timestamp when the rule was created.

created_by string required nullable

User who created the rule.

enabled boolean required

Whether the rule is enabled.

id string required

Unique rule identifier.

kind enum required

Whether the rule creates alerts (alert) or only stores matching events (signal).

Values: alert signal
metadata object required
builder_type string · max length: 64

Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

description string · max length: 1024

Human-readable description of the rule.

name string · min length: 1 · max length: 256 required

Rule name (must be unique within the space).

owner string · max length: 256

Owner of the rule.

tags string[] · min items: 1 · max items: 20

Tags for categorization, e.g. ["production", "infra"].

version integer · min: 1 · max: 9007199254740991 required

Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

no_data_strategy enum

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_status emit recover none
query union oneOf required

Detection query configuration.

Same options as query
recovery_strategy enum

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_breach query none
schedule object required

Execution schedule configuration.

every string · max length: 32 required

Execution interval, e.g. 1m, 5m, 1h.

lookback string · max length: 32

Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

time_field string · min length: 1 · max length: 128 · default: @timestamp

Document field used as the event time when applying the lookback window. Defaults to @timestamp.

updated_at string required

ISO timestamp when the rule was last updated.

updated_by string required nullable

User who last updated the rule.

version string

The saved object version token of the rule, used for optimistic concurrency control.