Create a rule | Kibana Serverless API documentation

Create a rule Experimental

POST /api/alerting/v2/rules

Spaces method and path for this operation:

post /s/{space_id}/api/alerting/v2/rules

Refer to Spaces for more information.

Creates a rule with a server-generated identifier. To create or replace a rule with a client-supplied identifier, use PUT /api/alerting/v2/rules/{id}/.

[Required authorization] Route required privileges: manage_alerting-v2-rules.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

artifacts array[object]

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.

Not more than 100 elements.
Hide artifacts attributes Show artifacts attributes object
- data object Required
  
  Structured artifact data.
  
  Additional properties are allowed.
- id string Required
  
  Artifact identifier.
  
  Minimum length is 1, maximum length is 150.
- type string Required
  
  Artifact type.
  
  Minimum length is 1, maximum length is 128.
grouping object

Grouping configuration.

Additional properties are NOT allowed.
Hide grouping attribute Show grouping attribute object
- fields array[string] Required
  
  Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
  
  Not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.
kind string Required
Whether the rule creates alerts (alert) or only stores matching events (signal).

Any of:
string-1 string string-2 string

Creates an alert for each matching group and tracks it until it recovers. Use this when you want to detect a problem and notify or automate a response.

Value is alert.

Stores each match as a rule event you can query. Alerts are not created and notifications are not sent.

Value is signal.
metadata object Required

Rule metadata.

Additional properties are NOT allowed.
Hide metadata attributes Show metadata attributes object
- builder_type string
  
  Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.
  
  Maximum length is 64.
- description string
  
  Human-readable description of the rule.
  
  Maximum length is 1024.
- name string Required
  
  Rule name (must be unique within the space).
  
  Minimum length is 1, maximum length is 256.
- routing_tags array[string]
  
  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".
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
- tags array[string]
  
  Tags for categorization, e.g. ["production", "infra"].
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
no_data object
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:
ignore object keep_last object resolve object alert object
Does not check whether a group still has data. Missing groups do not produce no_data events.
Hide attribute Show attribute

strategy string Required Discriminator

Value is ignore.
Holds the alert's current status when the rule finds no data.
Hide attributes Show attributes

query string

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.

Minimum length is 1, maximum length is 10000.

strategy string Required Discriminator

Value is keep_last.
Closes the alert the first time the rule finds no data for a group.
Hide attributes Show attributes

query string

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.

Minimum length is 1, maximum length is 10000.

strategy string Required Discriminator

Value is resolve.
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.
Hide attributes Show attributes

query string

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.

Minimum length is 1, maximum length is 10000.

strategy string Required Discriminator

Value is alert.
query object Required

ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.

Additional properties are NOT allowed.
Hide query attributes Show query attributes object
- base string Required
  
  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.
  
  Minimum length is 1, maximum length is 10000.
- breach object
  
  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.
  
  Additional properties are NOT allowed.
  Hide breach attribute Show breach attribute object
  
  segment string Required
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
recovery object
When an alert recovers. Required when kind is alert. Not allowed when kind is signal.
One of:
no_breach object condition object query object manual object
Recovers the alert when its group no longer appears in the breach results.
Hide attribute Show attribute

strategy string Required Discriminator

Value is no_breach.
Recovers the alert when query.base plus segment returns the group. Requires query.breach.
Hide attributes Show attributes

segment string Required

ES|QL clause appended to query.base, for example WHERE avg_cpu < 0.60. Don't include a FROM clause.

Minimum length is 1, maximum length is 10000.

strategy string Required Discriminator

Value is condition.
Recovers the alert when this separate query returns the group.
Hide attributes Show attributes

query string Required

Independent ES|QL query, including its own FROM clause. A matching group recovers the alert.

Minimum length is 1, maximum length is 10000.

strategy string Required Discriminator

Value is query.
Does not recover automatically. Close the alert with a user action. state_transition.recovering has no effect.
Hide attribute Show attribute

strategy string Required Discriminator

Value is manual.
schedule object Required

Execution schedule configuration.

Additional properties are NOT allowed.
Hide schedule attributes Show schedule attributes object
- every string Required
  
  Execution interval, e.g. 1m, 5m, 1h.
  
  Maximum length is 32.
- lookback string
  
  Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.
  
  Maximum length is 32.
state_transition object

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.

Additional properties are NOT allowed.
Hide state_transition attributes Show state_transition attributes object
- pending object
  
  Delay before a match opens an alert.
  
  Additional properties are NOT allowed.
  Hide pending attributes Show pending attributes object
  
  count integer
  
  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.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
- recovering object
  
  Delay before a recovered match closes the alert. Has no effect when recovery.strategy is manual.
  
  Additional properties are NOT allowed.
  Hide recovering attributes Show recovering attributes object
  
  count integer
  
  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.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
time_field string

Document field Kibana uses with schedule.lookback to time-filter query.base.

Minimum length is 1, maximum length is 256. Default value is @timestamp.

Responses

201 application/json

Returns the newly created rule.
Hide response attributes Show response attributes object
- artifacts array[object]
  
  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.
  
  Not more than 100 elements.
  
  Hide artifacts attributes Show artifacts attributes object
  
  data object Required
  
  Structured artifact data.
  
  Additional properties are allowed.
  
  id string Required
  
  Artifact identifier.
  
  Minimum length is 1, maximum length is 150.
  
  type string Required
  
  Artifact type.
  
  Minimum length is 1, maximum length is 128.
- created_at string(date-time) Required
  
  ISO timestamp when the rule was created.
  
  Format should match the following pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$.
- created_by object Required
  
  Actor who created the rule.
  
  Additional properties are NOT allowed.
  
  Hide created_by attribute Show created_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- enabled boolean Required
  
  Whether the rule is enabled.
- grouping object
  
  Grouping configuration.
  
  Additional properties are NOT allowed.
  
  Hide grouping attribute Show grouping attribute object
  
  fields array[string] Required
  
  Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.
  
  Not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.
- id string Required
  
  Unique rule identifier.
- kind string Required
  Whether the rule creates alerts (alert) or only stores matching events (signal).
  
  Any of:
  string-1 string string-2 string
  
  Creates an alert for each matching group and tracks it until it recovers. Use this when you want to detect a problem and notify or automate a response.
  
  Value is alert.
  
  Stores each match as a rule event you can query. Alerts are not created and notifications are not sent.
  
  Value is signal.
- metadata object Required
  
  Rule metadata.
  
  Additional properties are NOT allowed.
  
  Hide metadata attributes Show metadata attributes object
  
  builder_type string
  
  Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.
  
  Maximum length is 64.
  
  description string
  
  Human-readable description of the rule.
  
  Maximum length is 1024.
  
  name string Required
  
  Rule name (must be unique within the space).
  
  Minimum length is 1, maximum length is 256.
  
  routing_tags array[string]
  
  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".
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
  
  tags array[string]
  
  Tags for categorization, e.g. ["production", "infra"].
  
  At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.
- no_data object
  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:
  ignore object keep_last object resolve object alert object
  
  Holds the alert's current status when the rule finds no data.
  
  Hide attributes Show attributes
  
  query string
  
  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.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is keep_last.
  
  Closes the alert the first time the rule finds no data for a group.
  
  Hide attributes Show attributes
  
  query string
  
  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.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is resolve.
  
  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.
  
  Hide attributes Show attributes
  
  query string
  
  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.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is alert.
- query object Required
  
  ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.
  
  Additional properties are NOT allowed.
  
  Hide query attributes Show query attributes object
  
  base string Required
  
  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.
  
  Minimum length is 1, maximum length is 10000.
  
  breach object
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide breach attribute Show breach attribute object
  
  segment string Required
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
- recovery object
  When an alert recovers. Required when kind is alert. Not allowed when kind is signal.
  
  One of:
  no_breach object condition object query object manual object
  
  Recovers the alert when query.base plus segment returns the group. Requires query.breach.
  
  Hide attributes Show attributes
  
  segment string Required
  
  ES|QL clause appended to query.base, for example WHERE avg_cpu < 0.60. Don't include a FROM clause.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is condition.
  
  Recovers the alert when this separate query returns the group.
  
  Hide attributes Show attributes
  
  query string Required
  
  Independent ES|QL query, including its own FROM clause. A matching group recovers the alert.
  
  Minimum length is 1, maximum length is 10000.
  
  strategy string Required Discriminator
  
  Value is query.
- schedule object Required
  
  Execution schedule configuration.
  
  Additional properties are NOT allowed.
  
  Hide schedule attributes Show schedule attributes object
  
  every string Required
  
  Execution interval, e.g. 1m, 5m, 1h.
  
  Maximum length is 32.
  
  lookback string
  
  Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.
  
  Maximum length is 32.
- state_transition object
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide state_transition attributes Show state_transition attributes object
  
  pending object
  
  Delay before a match opens an alert.
  
  Additional properties are NOT allowed.
  
  Hide pending attributes Show pending attributes object
  
  count integer
  
  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.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
  
  recovering object
  
  Delay before a recovered match closes the alert. Has no effect when recovery.strategy is manual.
  
  Additional properties are NOT allowed.
  
  Hide recovering attributes Show recovering attributes object
  
  count integer
  
  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.
  
  Minimum value is 0, maximum value is 1000.
  
  operator string
  
  When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.
  
  Values are and or or.
  
  timeframe string
  
  Duration the condition must hold, for example 5m. Combine with count using operator.
  
  Maximum length is 32.
- time_field string
  
  Document field Kibana uses with schedule.lookback to time-filter query.base.
  
  Minimum length is 1, maximum length is 256. Default value is @timestamp.
- updated_at string(date-time) Required
  
  ISO timestamp when the rule was last updated.
  
  Format should match the following pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$.
- updated_by object Required
  
  Actor who last updated the rule.
  
  Additional properties are NOT allowed.
  
  Hide updated_by attribute Show updated_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- version integer Required
  
  Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.
  
  Minimum value is 1, maximum value is 9007199254740991.
400 application/json

Indicates an invalid schema or parameters.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
401 application/json

Indicates the request was not authenticated.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
403 application/json

Indicates the user does not have the required privileges to perform the request.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
500 application/json

Indicates an unexpected server-side error.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
503 application/json

Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.

POST /api/alerting/v2/rules

curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/v2/rules' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu > 0.9"
    }
  },
  "recovery": {
    "strategy": "no_breach"
  },
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending": {
      "count": 1
    },
    "recovering": {
      "count": 1
    }
  },
  "time_field": "@timestamp"
}'

Request example

{
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu > 0.9"
    }
  },
  "recovery": {
    "strategy": "no_breach"
  },
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending": {
      "count": 1
    },
    "recovering": {
      "count": 1
    }
  },
  "time_field": "@timestamp"
}

Response examples (201)

{
  "created_at": "2026-01-15T12:00:00.000Z",
  "created_by": {
    "profile_uid": "u_elastic_0"
  },
  "enabled": true,
  "grouping": {
    "fields": [
      "host.name"
    ]
  },
  "id": "rule-1",
  "kind": "alert",
  "metadata": {
    "description": "Alerts when average CPU usage exceeds a threshold.",
    "name": "Host CPU high",
    "routing_tags": [
      "sre-oncall"
    ],
    "tags": [
      "production",
      "infra"
    ]
  },
  "no_data": {
    "strategy": "keep_last"
  },
  "query": {
    "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
    "breach": {
      "segment": "WHERE avg_cpu > 0.9"
    }
  },
  "recovery": {
    "strategy": "no_breach"
  },
  "schedule": {
    "every": "1m",
    "lookback": "5m"
  },
  "state_transition": {
    "pending": {
      "count": 1
    },
    "recovering": {
      "count": 1
    }
  },
  "time_field": "@timestamp",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "updated_by": {
    "profile_uid": "u_elastic_0"
  },
  "version": 1
}

Response examples (400)

{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "metadata": [
        "Required"
      ]
    }
  },
  "error": "Bad Request",
  "message": "metadata: Required"
}

Response examples (401)

{
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Authentication required to access this API."
}

Response examples (403)

{
  "code": "FORBIDDEN",
  "error": "Forbidden",
  "message": "The current user does not have the required privileges for this request."
}

Response examples (500)

{
  "code": "INTERNAL_SERVER_ERROR",
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}

Response examples (503)

{
  "code": "ALERTING_DISABLED",
  "error": "Service Unavailable",
  "message": "Alerting is disabled."
}