Create a rule

Base URL
https://{kibana_url}
Auth

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

id string required

The identifier for the rule. If it is omitted, an ID is randomly generated.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

actions object[] · default: []
alerts_filter object

Conditions that affect whether the action runs. If you specify multiple conditions, all conditions must be met for the action to run. For example, if an alert occurs within the specified time frame and matches the query, the action runs.

query object
dsl string

A filter written in Elasticsearch Query Domain Specific Language (DSL).

filters object[] required

A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

$state object
store enum required

A filter can be either specific to an application context or applied globally.

Values: appState globalState
meta map string to object required
query map string to object
kql string required

A filter written in Kibana Query Language (KQL).

timeframe object

Defines a period that limits whether the action runs.

days enum[] required

Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.

Values: 1 2 3 4 5 6 7
hours object required

Defines the range of time in a day that the action can run. If the start value is 00:00 and the end value is 24:00, actions be generated all day.

end string required

The end of the time frame in 24-hour notation (hh:mm).

start string required

The start of the time frame in 24-hour notation (hh:mm).

timezone string required

The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.

frequency object
notify_when enum required

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values: onActionGroupChange onActiveAlert onThrottleInterval
summary boolean required

Indicates whether the action is a summary.

throttle string required nullable

The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if notify_when is set to onThrottleInterval. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

group string

The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.

id string required

The identifier for the connector saved object.

params map string to object · default: {}

The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.

use_alert_data_for_template boolean

Indicates whether to use alert data as a template.

uuid string

A universally unique identifier (UUID) for the action.

alert_delay object

Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

active number required

The number of consecutive runs that must meet the rule conditions.

artifacts object
dashboards object[] · max items: 10
id string required
investigation_guide object
blob string · max length: 10000 required
consumer string required

The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.

enabled boolean · default: true

Indicates whether you want to run the rule on an interval basis after it is created.

flapping object nullable

When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

look_back_window number · min: 2 · max: 20 required

The minimum number of runs in which the threshold must be met.

status_change_threshold number · min: 2 · max: 20 required

The minimum number of times an alert must switch states in the look back window.

name string required

The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.

notify_when enum nullable

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values: onActionGroupChange onActiveAlert onThrottleInterval
rule_type_id string required

The rule type identifier.

schedule object required

The check interval, which specifies how frequently the rule conditions are checked.

interval string required

The interval is specified in seconds, minutes, hours, or days.

tags string[] · default: []

The tags for the rule.

throttle string nullable

Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

params union anyOf · default: {}

The parameters for the rule.

Any of:

The parameters for the APM anomaly rule. These parameters are appropriate when rule_type_id is apm.rules.anomaly.

serviceName string

The service name from APM

transactionType string

The transaction type from APM

windowSize number required

The window size

windowUnit enum required

The window size unit

Values: m h d
environment string required

The environment from APM

anomalySeverityType enum required

The anomaly threshold value

Values: critical major minor warning

Responses

Indicates a successful call.

application/json
actions object[] required
alerts_filter object

Defines a period that limits whether the action runs.

query object
dsl string

A filter written in Elasticsearch Query Domain Specific Language (DSL).

filters object[] required

A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

$state object
store enum required

A filter can be either specific to an application context or applied globally.

Values: appState globalState
meta map string to object required
query map string to object
kql string required

A filter written in Kibana Query Language (KQL).

timeframe object
days enum[] required

Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.

Values: 1 2 3 4 5 6 7
hours object required
end string required

The end of the time frame in 24-hour notation (hh:mm).

start string required

The start of the time frame in 24-hour notation (hh:mm).

timezone string required

The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.

connector_type_id string required

The type of connector. This property appears in responses but cannot be set in requests.

frequency object
notify_when enum required

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values: onActionGroupChange onActiveAlert onThrottleInterval
summary boolean required

Indicates whether the action is a summary.

throttle string required nullable

The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

group string

The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.

id string required

The identifier for the connector saved object.

params map string to object required

The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.

use_alert_data_for_template boolean

Indicates whether to use alert data as a template.

uuid string

A universally unique identifier (UUID) for the action.

active_snoozes string[]
alert_delay object

Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

active number required

The number of consecutive runs that must meet the rule conditions.

api_key_created_by_user boolean nullable

Indicates whether the API key that is associated with the rule was created by the user.

api_key_owner string required nullable

The owner of the API key that is associated with the rule and used to run background tasks.

artifacts object
dashboards object[]
id string required
investigation_guide object
blob string required

User-created content that describes alert causes and remdiation.

consumer string required

The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.

created_at string required

The date and time that the rule was created.

created_by string required nullable

The identifier for the user that created the rule.

enabled boolean required

Indicates whether you want to run the rule on an interval basis after it is created.

execution_status object required
error object
message string required

Error message.

reason enum required

Reason for error.

Values: read decrypt execute unknown license timeout disabled validate
last_duration number

Duration of last execution of the rule.

last_execution_date string required

The date and time when rule was executed last.

status enum required

Status of rule execution.

Values: ok active error warning pending unknown
warning object
message string required

Warning message.

reason enum required

Reason for warning.

Values: maxExecutableActions maxAlerts maxQueuedActions ruleExecution
flapping object nullable

When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

look_back_window number · min: 2 · max: 20 required

The minimum number of runs in which the threshold must be met.

status_change_threshold number · min: 2 · max: 20 required

The minimum number of times an alert must switch states in the look back window.

id string required

The identifier for the rule.

is_snoozed_until string nullable

The date when the rule will no longer be snoozed.

last_run object nullable
alerts_count object required
active number nullable

Number of active alerts during last run.

ignored number nullable

Number of ignored alerts during last run.

new number nullable

Number of new alerts during last run.

recovered number nullable

Number of recovered alerts during last run.

outcome enum required

Outcome of last run of the rule. Value could be succeeded, warning or failed.

Values: succeeded warning failed
outcome_msg string[] nullable
outcome_order number

Order of the outcome.

warning enum nullable

Warning of last rule execution.

Values: read decrypt execute unknown license timeout disabled validate maxExecutableActions maxAlerts maxQueuedActions ruleExecution
mapped_params map string to object
monitoring object

Monitoring details of the rule.

run object required

Rule run details.

calculated_metrics object required

Calculation of different percentiles and success ratio.

p50 number
p95 number
p99 number
success_ratio number required
history object[] required

History of the rule run.

duration number

Duration of the rule run.

outcome enum

Outcome of last run of the rule. Value could be succeeded, warning or failed.

Values: succeeded warning failed
success boolean required

Indicates whether the rule run was successful.

timestamp number required

Time of rule run.

last_run object required
metrics object required
duration number

Duration of most recent rule run.

gap_duration_s number nullable

Duration in seconds of rule run gap.

gap_range object nullable
gte string required

End of the gap range.

lte string required

Start of the gap range.

total_alerts_created number nullable

Total number of alerts created during last rule run.

total_alerts_detected number nullable

Total number of alerts detected during last rule run.

total_indexing_duration_ms number nullable

Total time spent indexing documents during last rule run in milliseconds.

total_search_duration_ms number nullable

Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.

timestamp string required

Time of the most recent rule run.

mute_all boolean required

Indicates whether all alerts are muted.

muted_alert_ids string[] required
name string required

The name of the rule.

next_run string nullable

Date and time of the next run of the rule.

notify_when enum nullable

Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

Values: onActionGroupChange onActiveAlert onThrottleInterval
params map string to object required

The parameters for the rule.

revision number required

The rule revision number.

rule_type_id string required

The rule type identifier.

running boolean nullable

Indicates whether the rule is running.

schedule object required
interval string required

The interval is specified in seconds, minutes, hours, or days.

scheduled_task_id string

Identifier of the scheduled task.

snooze_schedule object[]
duration number required

Duration of the rule snooze schedule.

id string

Identifier of the rule snooze schedule.

rRule object required
byhour number[] nullable
byminute number[] nullable
bymonth number[] nullable
bymonthday number[] nullable
bysecond number[] nullable
bysetpos number[] nullable
byweekday (number | string)[] nullable
byweekno number[] nullable
byyearday number[] nullable
count number

Number of times the rule should recur until it stops.

dtstart string required

Rule start date in Coordinated Universal Time (UTC).

freq enum

Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.

Values: 0 1 2 3 4 5 6
interval number

Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.

tzid string required

Indicates timezone abbreviation.

until string

Recur the rule until this date.

wkst enum

Indicates the start of week, defaults to Monday.

Values: MO TU WE TH FR SA SU
skipRecurrences string[]
tags string[] required
throttle string nullable deprecated

Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

updated_at string required

The date and time that the rule was updated most recently.

updated_by string required nullable

The identifier for the user that updated this rule most recently.

view_in_app_relative_url string nullable

Relative URL to view rule in the app.

400

Indicates an invalid schema or parameters.

403

Indicates that this call is forbidden.

409

Indicates that the rule id is already in use.

Base URL
https://{kibana_url}