Skip to main content

Update Unified Alert

PUT 
/v2/unified-alerts/:type/:id

Update an existing unified alert by its type and ID.

Request​

Path Parameters

    type stringrequired

    The type of the unified alert. options are: logs, metrics. Make sure alertConfiguration.type matches the type parameter

    id stringrequired

    The ID of the unified alert.

Body

required
    title stringrequired

    The title of the unified alert.

    description string

    A description of the unified alert.

    tags string[]

    Tags associated with the unified alert.

    linkedPanel object

    Represents the Unified Dashboards panel linked to this alert.

    This provides a direct reference to the visualization source of the alert, enabling navigation from alert → panel for context and troubleshooting.

    The panel is included in the notification for quick access and used by the AI Agent to run an RCA when enabled.

    folderId stringrequired

    The folder ID where the dashboard is located.

    dashboardId stringrequired

    The dashboard ID where he panel is located.

    panelId stringrequired

    The panel ID associated to this alert.

    runbook string

    The runbook for the alert.

    rca boolean

    Whether RCA (Root Cause Analysis) is enabled for the alert.

    rcaNotificationEndpointIds integer[]

    Notification endpoint IDs for RCA.

    useAlertNotificationEndpointsForRca boolean

    Whether to use alert notification endpoints for RCA.

    recipients object

    Add email addresses and/or endpoint channels to automatically receive notifications with sample data when the alert triggers.

    emails string[]

    Array of email addresses to be notified when the alert triggers.

    notificationEndpointIds int32[]

    Array of IDs of pre-configured endpoint channels to notify when the alert triggers.

    alertConfiguration object required
    oneOf
    type string

    Possible values: [LOG_ALERT]

    suppressNotificationsMinutes int32

    Possible values: >= 5 and <= 1440

    Add a waiting period in minutes to space out notifications. (The alert will still trigger but will not send out notifications during the waiting period.)

    alertOutputTemplateType AlertOutputTemplateType

    Possible values: [JSON, TEXT]

    The output template type for the alert notification.

    searchTimeFrameMinutes int32

    Possible values: >= 5 and <= 1440

    The time frame for evaluating the log data is a sliding window, with 1 minute granularity.

    The recommended minimum and maximum values are not validated, but needed to guarantee the alert's accuracy.

    The minimum recommended time frame is 5 minutes, as anything shorter will be less reliable and unnecessarily resource-heavy.

    The maximum recommended time frame is 1440 minutes (24 hours). The alert runs on the index from today and yesterday (in UTC) and the maximum time frame increases throughout the day, reaching 48 hours exactly before midnight UTC.

    The default value is 5.

    subComponents object[]required

    Possible values: >= 1

  • Array [
    • queryDefinition object

    Determines when the alert should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions.

    query string

    Default value: *

    Provide a Kibana search query written in Lucene syntax. The search query together with the filters select for the relevant logs. Cannot be null - send an asterisk wildcard * if not using a search query.

    filters object

    Apply must and must_not filters to the monitoring alert. Filters are more efficient compared to a query, so it's recommended to opt for a filter over a query, where possible. See Elasticsearch Bool-Query for more detail.

    bool object

    Runs Elasticsearch Bool Query filters on the data (before the search query is applied). The most efficient way to grab the logs you are looking for.

    must object[]
  • Array [
    • match_phrase object
    Field object
    query string
  • ]
    • must_not object[]
  • Array [
    • match_phrase object
    Field object
    query string
  • ]
    • groupBy string[]nullable

    Possible values: <= 3

    Specify 1-3 fields by which to group the results and count them. If you apply a group by operation, the alert returns a count of the results aggregated by unique values.

    aggregation object

    Specifies a trigger condition that acts as a threshold.

    aggregationType string

    Possible values: [SUM, MIN, MAX, AVG, COUNT, UNIQUE_COUNT, NONE, PERCENTAGE, PERCENTILE]

    Specifies the aggregation operator.

    • If COUNT, fieldToAggregateOn must be null, and groupBy fields must not be empty.
    • If NONE, fieldToAggregateOn must be null, and groupBy field must not be empty (or null).
    • If PERCENTAGE, valueToAggregateOn must be specified.
    • If any other operator type (other than NONE or COUNT), fieldToAggregateOn must not be null.
    fieldToAggregateOn string

    Selects the field on which to run the aggregation for the trigger condition.

    • Cannot be a field already in use for groupBy.
    valueToAggregateOn string

    Used by the PERCENTAGE aggregation to select the field’s value. This value is used to determine if its ratio out of the total amount of logs in the query satisfies the trigger condition.

    • Only relevant for the PERCENTAGE aggregation.
    shouldQueryOnAllAccounts boolean

    Default value: true

    Only applicable when the alert is run from the main account. If true, the alert runs on the main account and all associated searchable sub accounts. If false, specify relevant account IDs for the alert to monitor using the accountIdsToQueryOn field.

    accountIdsToQueryOn int32[]

    Specify Account IDs to select which accounts the alert should monitor. The alert will be checked only on these accounts.

    trigger object

    Sets the triggering threshold and severity tab to label the event when the alert triggers.

    operator string

    Possible values: [LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN_OR_EQUALS, EQUALS, NOT_EQUALS]

    Specifies the operator for evaluating the results.

    severityThresholdTiers object

    Possible values: [INFO, LOW, MEDIUM, HIGH, SEVERE]

    Default value: [object Object]

    Sets a severity label per trigger threshold as a key:value pair. If using more than one sub-component, only 1 severityThresholdTiers is allowed. Otherwise, 1 per enum are allowed (for a total of 5 thresholds of increasing severities). Increasing severity must adhere to the logic of the operator.

    output object

    Selects the data output to be sent in the notification when the alert triggers. Not applicable, when grouping by fields or aggregating results, as the output is auto-selected.

    shouldUseAllFields boolean

    Default value: true

    If true, the notification output will include entire logs with all of their fields in the sample data.

  • ]
    • correlations object

    Only applicable when multiple sub-components are in use. Selects a logic for correlating the alert’s sub-components. AND is currently the only supported operator. When AND is the correlationOperator, both sub-components must meet their triggering criteria for the alert to trigger.

    correlationOperators string[]

    Possible values: [AND]

    joins object[]

    Default value: false

    Specifies which group by fields must have the same values to trigger the alert. Joins the group by fields from the first and second sub-components. The key represents the index of the sub component in the array (See the example - the index of the first sub-component is 0, the second is 1). The fields must be ordered pairs of the group by fields already in use in the queryDefinition.

    schedule object

    Defines the frequency and the time frame in which an alert will be evaluated.

    cronExpression string

    Cron job for the intervals schedule.

    timezone string

    Time zone for the cron job. If no time zone is selected, UTC will be used by default.

    enabled boolean

    Whether the alert is enabled.

Responses​

Unified alert updated successfully.

Schema
    id string

    The ID of the unified alert.

    title stringrequired

    The title of the unified alert.

    description string

    A description of the unified alert.

    tags string[]

    Tags associated with the unified alert.

    linkedPanel object

    Represents the Unified Dashboards panel linked to this alert.

    This provides a direct reference to the visualization source of the alert, enabling navigation from alert → panel for context and troubleshooting.

    The panel is included in the notification for quick access and used by the AI Agent to run an RCA when enabled.

    folderId stringrequired

    The folder ID where the dashboard is located.

    dashboardId stringrequired

    The dashboard ID where he panel is located.

    panelId stringrequired

    The panel ID associated to this alert.

    runbook string

    The runbook for the alert.

    rca boolean

    Whether RCA (Root Cause Analysis) is enabled for the alert.

    rcaNotificationEndpointIds integer[]

    Notification endpoint IDs for RCA.

    useAlertNotificationEndpointsForRca boolean

    Whether to use alert notification endpoints for RCA.

    recipients object

    Add email addresses and/or endpoint channels to automatically receive notifications with sample data when the alert triggers.

    emails string[]

    Array of email addresses to be notified when the alert triggers.

    notificationEndpointIds int32[]

    Array of IDs of pre-configured endpoint channels to notify when the alert triggers.

    alertConfiguration object required
    oneOf
    type string

    Possible values: [LOG_ALERT]

    suppressNotificationsMinutes int32

    Possible values: >= 5 and <= 1440

    Add a waiting period in minutes to space out notifications. (The alert will still trigger but will not send out notifications during the waiting period.)

    alertOutputTemplateType AlertOutputTemplateType

    Possible values: [JSON, TEXT]

    The output template type for the alert notification.

    searchTimeFrameMinutes int32

    Possible values: >= 5 and <= 1440

    The time frame for evaluating the log data is a sliding window, with 1 minute granularity.

    The recommended minimum and maximum values are not validated, but needed to guarantee the alert's accuracy.

    The minimum recommended time frame is 5 minutes, as anything shorter will be less reliable and unnecessarily resource-heavy.

    The maximum recommended time frame is 1440 minutes (24 hours). The alert runs on the index from today and yesterday (in UTC) and the maximum time frame increases throughout the day, reaching 48 hours exactly before midnight UTC.

    The default value is 5.

    subComponents object[]required

    Possible values: >= 1

  • Array [
    • queryDefinition object

    Determines when the alert should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions.

    query string

    Default value: *

    Provide a Kibana search query written in Lucene syntax. The search query together with the filters select for the relevant logs. Cannot be null - send an asterisk wildcard * if not using a search query.

    filters object

    Apply must and must_not filters to the monitoring alert. Filters are more efficient compared to a query, so it's recommended to opt for a filter over a query, where possible. See Elasticsearch Bool-Query for more detail.

    bool object

    Runs Elasticsearch Bool Query filters on the data (before the search query is applied). The most efficient way to grab the logs you are looking for.

    must object[]
  • Array [
    • match_phrase object
    Field object
    query string
  • ]
    • must_not object[]
  • Array [
    • match_phrase object
    Field object
    query string
  • ]
    • groupBy string[]nullable

    Possible values: <= 3

    Specify 1-3 fields by which to group the results and count them. If you apply a group by operation, the alert returns a count of the results aggregated by unique values.

    aggregation object

    Specifies a trigger condition that acts as a threshold.

    aggregationType string

    Possible values: [SUM, MIN, MAX, AVG, COUNT, UNIQUE_COUNT, NONE, PERCENTAGE, PERCENTILE]

    Specifies the aggregation operator.

    • If COUNT, fieldToAggregateOn must be null, and groupBy fields must not be empty.
    • If NONE, fieldToAggregateOn must be null, and groupBy field must not be empty (or null).
    • If PERCENTAGE, valueToAggregateOn must be specified.
    • If any other operator type (other than NONE or COUNT), fieldToAggregateOn must not be null.
    fieldToAggregateOn string

    Selects the field on which to run the aggregation for the trigger condition.

    • Cannot be a field already in use for groupBy.
    valueToAggregateOn string

    Used by the PERCENTAGE aggregation to select the field’s value. This value is used to determine if its ratio out of the total amount of logs in the query satisfies the trigger condition.

    • Only relevant for the PERCENTAGE aggregation.
    shouldQueryOnAllAccounts boolean

    Default value: true

    Only applicable when the alert is run from the main account. If true, the alert runs on the main account and all associated searchable sub accounts. If false, specify relevant account IDs for the alert to monitor using the accountIdsToQueryOn field.

    accountIdsToQueryOn int32[]

    Specify Account IDs to select which accounts the alert should monitor. The alert will be checked only on these accounts.

    trigger object

    Sets the triggering threshold and severity tab to label the event when the alert triggers.

    operator string

    Possible values: [LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN_OR_EQUALS, EQUALS, NOT_EQUALS]

    Specifies the operator for evaluating the results.

    severityThresholdTiers object

    Possible values: [INFO, LOW, MEDIUM, HIGH, SEVERE]

    Default value: [object Object]

    Sets a severity label per trigger threshold as a key:value pair. If using more than one sub-component, only 1 severityThresholdTiers is allowed. Otherwise, 1 per enum are allowed (for a total of 5 thresholds of increasing severities). Increasing severity must adhere to the logic of the operator.

    output object

    Selects the data output to be sent in the notification when the alert triggers. Not applicable, when grouping by fields or aggregating results, as the output is auto-selected.

    shouldUseAllFields boolean

    Default value: true

    If true, the notification output will include entire logs with all of their fields in the sample data.

  • ]
    • correlations object

    Only applicable when multiple sub-components are in use. Selects a logic for correlating the alert’s sub-components. AND is currently the only supported operator. When AND is the correlationOperator, both sub-components must meet their triggering criteria for the alert to trigger.

    correlationOperators string[]

    Possible values: [AND]

    joins object[]

    Default value: false

    Specifies which group by fields must have the same values to trigger the alert. Joins the group by fields from the first and second sub-components. The key represents the index of the sub component in the array (See the example - the index of the first sub-component is 0, the second is 1). The fields must be ordered pairs of the group by fields already in use in the queryDefinition.

    schedule object

    Defines the frequency and the time frame in which an alert will be evaluated.

    cronExpression string

    Cron job for the intervals schedule.

    timezone string

    Time zone for the cron job. If no time zone is selected, UTC will be used by default.

    enabled boolean

    Whether the alert is enabled.

    createdAt integer

    The timestamp when the alert was created in seconds since Unix epoch.

    updatedAt integer

    The timestamp when the alert was last updated in seconds since Unix epoch.

    createdBy string

    The email of the user or api token name who created the alert.

    updatedBy string

    The email of the user or api token name who last updated the alert.

Loading...