Enable rules matching a query (dry-run by default) Generally available; added in 9.6.0

POST /api/alerting/v2/rules/_enable_by_query
Api key auth Basic auth

Spaces method and path for this operation:

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

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

application/json

Body

  • filter string

    KQL filter string to match target resources. At most 10000 matching resources are processed per request. Cannot be empty; to target every resource use match_all: true.

    Minimum length is 1, maximum length is 4096.

  • force boolean

    When true, executes the operation. When false (default), returns a dry-run preview with match_count and a sample of matching resource IDs so the client can verify before committing.

    Default value is false.

  • match_all boolean

    When true, targets every resource. Requires an explicit opt-in. Omitted by default.

    Value is true.

  • search string

    Free-text search string matched against the resource-defined searchable fields. Cannot be empty; to target every resource use match_all: true.

    Minimum length is 1, maximum length is 256.

Responses

  • 200 application/json

    Returns a dry-run preview by default, or the executed operation when force is true.

    Any of:
    Kibana_HTTP_APIs_alerting_bulk_dry_run_response object Kibana_HTTP_APIs_alerting_bulk_operation_response object
  • 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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      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 structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      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/_enable_by_query 
curl \
 --request POST 'https://localhost:5601/api/alerting/v2/rules/_enable_by_query' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "filter": "tags: production"
}'
Request example 
{
  "filter": "tags: production"
}
Response examples (200) 
{
  "match_count": 2,
  "sample": [
    "rule-1",
    "rule-2"
  ]
}
Response examples (400) 
{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "": [
        "At least one of filter, search, or match_all must be provided."
      ]
    }
  },
  "error": "Bad Request",
  "message": "At least one of filter, search, or match_all must be provided."
}
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."
}