Preview rule alerts generated on specified time range

Base URL
https://{kibana_url}
  • POST /api/detection_engine/rules/preview
  • POST /s/{space_id}/api/detection_engine/rules/preview
Auth

Simulates a detection rule using the same rule type and query logic as a persisted rule, over a short time window, without persisting a rule or writing alerts. Use the response to validate queries, see sample matching documents, and inspect execution logs. Pair invocationCount and timeframeEnd to cap run time.

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.

Query parameters

enable_logged_requests boolean

Enables logging and returning in response ES queries, performed during rule execution

Request body

Rule create payload (same shape as POST /api/detection_engine/rules for a given type) plus invocationCount and timeframeEnd to control how the preview is executed. Optional enable_logged_requests surfaces Elasticsearch request logging for debugging.

Any of:
type: eql
type enum required

Rule type

Values: eql
alias_purpose enum
Values: savedObjectConversion savedObjectImport
alias_target_id string
author string[]

The rule’s author.

building_block_type string

Determines if the rule acts as a building block. If yes, the value must be default. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. For more information, refer to About building block rules.

description string · min length: 1 required

The rule’s description.

enabled boolean

Determines whether the rule is enabled. Defaults to true.

false_positives string[]

String array used to describe common reasons why the rule may issue false-positive alerts. Defaults to an empty array.

from string · format: date-math

Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).

interval string

Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).

license string

The rule's license.

max_signals integer · min: 1

Maximum number of alerts the rule can create during a single run (the rule’s Max alerts per run advanced setting value). Defaults to 100.

Note

This setting can be superseded by the Kibana configuration setting xpack.alerting.rules.run.alerts.max, which determines the maximum alerts generated by any rule in the Kibana alerting framework. For example, if xpack.alerting.rules.run.alerts.max is set to 1000, the rule can generate no more than 1000 alerts even if max_signals is set higher.

meta object

Placeholder for metadata about the rule.

Note

This field is overwritten when you save changes to the rule’s settings.

name string · min length: 1 required

A human-readable name for the rule.

namespace string

Has no effect.

note string

Notes to help investigate alerts produced by the rule.

outcome enum
Values: exactMatch aliasMatch conflict
output_index string deprecated

(deprecated) Has no effect.

references string[]

Array containing notes about or references to relevant information about the rule. Defaults to an empty array.

response_actions union oneOf[]
One of:
action_type_id enum required
Values: .osquery
params object required
ecs_mapping map string to object

Map Osquery results columns or static values to Elastic Common Schema (ECS) fields. Example: "ecs_mapping": {"process.pid": {"field": "pid"}}

pack_id string · max length: 256

To specify a query pack, use the packId field. Example: "packId": "processes_elastic"

query string · max length: 30000

To run a single query, use the query field and enter a SQL query. Example: "query": "SELECT * FROM processes;"

saved_query_id string · max length: 256

To run a saved query, use the saved_query_id field and specify the saved query ID. Example: "saved_query_id": "processes_elastic"

timeout number

A timeout period, in seconds, after which the query will stop running. Overwriting the default timeout allows you to support queries that require more time to complete. The default and minimum supported value is 60. The maximum supported value is 900. Example: "timeout": 120.

risk_score integer · min: 0 · max: 100 required

A numerical representation of the alert's severity from 0 to 100, where:

  • 0 - 21 represents low severity
  • 22 - 47 represents medium severity
  • 48 - 73 represents high severity
  • 74 - 100 represents critical severity
rule_id string

A stable unique identifier for the rule object. It can be assigned during rule creation. It can be any string, but often is a UUID. It should be unique not only within a given Kibana space, but also across spaces and Elastic environments. The same prebuilt Elastic rule, when installed in two different Kibana spaces or two different Elastic environments, will have the same rule_ids.

rule_name_override string

Sets which field in the source event is used to populate the alert's signal.rule.name value (in the UI, this value is displayed on the Rules page in the Rule column). When unspecified, the rule’s name value is used. The source field must be a string data type.

setup string

Populates the rule’s setup guide with instructions on rule prerequisites such as required integrations, configuration steps, and anything else needed for the rule to work correctly.

severity enum required

Severity level of alerts produced by the rule, which must be one of the following:

  • low: Alerts that are of interest but generally not considered to be security incidents
  • medium: Alerts that require investigation
  • high: Alerts that require immediate investigation
  • critical: Alerts that indicate it is highly likely a security incident has occurred
Values: low medium high critical
tags string[]

String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

throttle union oneOf

Defines how often rule actions are taken.

Values: no_actions rule
timeline_id string

Timeline template ID

timeline_title string

Timeline template title

timestamp_override string

Sets the time field used to query indices. When unspecified, rules query the @timestamp field. The source field must be an Elasticsearch date data type.

timestamp_override_fallback_disabled boolean

Disables the fallback to the event's @timestamp field

to string
version integer · min: 1

The rule's version number.

  • For prebuilt rules it represents the version of the rule's content in the source detection-rules repository (and the corresponding security_detection_engine Fleet package that is used for distributing prebuilt rules).
  • For custom rules it is set to 1 when the rule is created.
Note

It is not incremented on each update. Compare this to the revision field.

language enum required
Values: eql
query string required

Query used by the rule to create alerts.

  • For indicator match rules, only the query’s results are used to determine whether an alert is generated.
  • ES|QL rules have additional query requirements. Refer to Create ES|QL rules for more information.
data_view_id string
event_category_override string
filters object[]

The query and filter context array used to define the conditions for when alerts are created from events. Defaults to an empty array.

Note

This field is not supported for ES|QL rules.

index string[]

Indices on which the rule functions. Defaults to the Security Solution indices defined on the Kibana Advanced Settings page (Kibana → Stack Management → Advanced Settings → securitySolution:defaultIndex).

Note

This field is not supported for ES|QL rules.

tiebreaker_field string

Sets a secondary field for sorting events

timestamp_field string

Specifies the name of the event timestamp field used for sorting a sequence of events. Not to be confused with timestamp_override, which specifies the more general field used for querying events within a range. Defaults to the @timestamp ECS field.

invocationCount integer required
timeframeEnd string · format: date-time required

Responses

Successful response

application/json
isAborted boolean
logs object[] required
duration integer required

Execution duration in milliseconds

errors string[] · format: nonempty required
startedAt string · format: nonempty · min length: 1

A string that does not contain only whitespace characters

warnings string[] · format: nonempty required
previewId string · format: nonempty · min length: 1

A string that does not contain only whitespace characters

Base URL
https://{kibana_url}