Disable rules matching a query (dry-run by default)

Disable rules matching a query (dry-run by default) Experimental; added in 9.5.0

POST /api/alerting/v2/rules/_disable_by_query

Api key auth Basic auth

Spaces method and path for this operation:

post /s/{space_id}/api/alerting/v2/rules/_disable_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
Dry-run preview returned by a by-query bulk endpoint when force is false.

Hide attributes Show attributes

match_count integer Required

Total number of resources matching the query. A dry run never fails on size, but if this exceeds 10000, re-sending the same query with force: true is rejected with BULK_QUERY_MATCH_LIMIT_EXCEEDED; narrow the query before executing.

Minimum value is 0, maximum value is 9007199254740991.

sample array[string] Required

Sample of matching resource IDs (up to 100) for spot-checking before executing.

Not more than 100 elements.
Result of an executed bulk operation.

Hide attributes Show attributes

affected_count integer Required

Number of resources the operation successfully touched.

Minimum value is 0, maximum value is 9007199254740991.

errors array[object] Required

Errors encountered during the operation.

Hide errors attributes Show errors attributes object

error object Required

Hide error attributes Show error attributes object

code string Required

A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.

details object

Optional structured context (e.g., validation field errors, conflict resource IDs).

Additional properties are allowed.

message string Required

A human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.

id string Required

The identifier of the resource that failed.
400 application/json

Indicates an invalid schema or parameters.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
401 application/json

Indicates the request was not authenticated.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
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
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
500 application/json

Indicates an unexpected server-side error.
Hide response attributes Show response attributes object
- code string Required
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.
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
  
  A stable, machine-readable error code (e.g., "RULE_NOT_FOUND", "INVALID_SCHEDULE"). Safe for clients to branch on.
- details object
  
  Optional structured context (e.g., validation field errors, conflict resource IDs).
  
  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 human-friendly explanation of the error. Subject to change without notice. Do not parse or rely on its content.

POST /api/alerting/v2/rules/_disable_by_query

curl \
 --request POST 'https://localhost:5601/api/alerting/v2/rules/_disable_by_query' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '"{\n  \"filter\": \"tags: production\"\n}"'

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."
}