Update a rule Experimental

PATCH /api/alerting/v2/rules/{id}
Api key auth

Spaces method and path for this operation:

patch /s/{space_id}/api/alerting/v2/rules/{id}

Refer to Spaces for more information.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule. Chosen at creation and permanent — it cannot be changed afterwards. Re-using the id of a deleted resource is allowed but discouraged: execution history, change history, and alert episodes recorded under that id are retained and are attributed to the new resource. Ids appear in URLs and logs, so keep them free of sensitive data.

    Minimum length is 1, maximum length is 150. Format should match the following pattern: ^[a-zA-Z0-9_-]+$.

application/json

Body

  • artifacts array[object] | null

    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.

  • metadata object

    Additional properties are NOT allowed.

    Hide metadata attributes Show metadata attributes object
    • builder_type string | null

      Maximum length is 64.

    • description string

      Human-readable description of the rule.

      Maximum length is 1024.

    • name string

      Rule name (must be unique within the space).

      Minimum length is 1, maximum length is 256.

    • routing_tags array[string] | null

      At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.

    • tags array[string] | null

      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
  • query object

    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
  • schedule object

    Additional properties are NOT allowed.

    Hide schedule attributes Show schedule attributes object
    • every string

      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. If omitted, the existing value is kept.

    Minimum length is 1, maximum length is 256.

Responses

  • 200 application/json

    Returns the updated 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
    • 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
    • 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.
  • 404 application/json

    Indicates a rule with the given ID does not exist.

    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.
  • 409 application/json

    Indicates the rule was concurrently updated by another caller.

    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.
PATCH /api/alerting/v2/rules/{id} 
curl \
 --request PATCH 'https://<KIBANA_URL>/api/alerting/v2/rules/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)"
  }
}'
Request example 
{
  "metadata": {
    "description": "Updated description.",
    "name": "Host CPU high (updated)"
  }
}
Response examples (200) 
{
  "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": "Updated description.",
    "name": "Host CPU high (updated)",
    "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": {
      "unknownField": [
        "Unrecognized key"
      ]
    }
  },
  "error": "Bad Request",
  "message": "Unrecognized key(s) in object: 'unknownField'"
}
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 (404) 
{
  "code": "RULE_NOT_FOUND",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Not Found",
  "message": "Rule with id \"rule-1\" not found"
}
Response examples (409) 
{
  "code": "RULE_VERSION_CONFLICT",
  "details": {
    "rule_id": "rule-1"
  },
  "error": "Conflict",
  "message": "Rule with id \"rule-1\" has already been updated by another user"
}
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."
}