Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Update Alert

View as MarkdownEdit this pageReport an issueSet up docs MCP
PUT/api/v2/alerts/{id}

Updates an existing alert

Authorizations

  • AuthorizationBearer API Keyheaderrequired
    `Authorization: Bearer <token>`

Path parameters

  • idstringrequired

    Alert ID

Request bodyJSON

  • thresholdnumberrequired

    Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.

    Example: 100
  • interval1mor5mor15mor30mor1hor6h+2 morerequired

    Evaluation interval for the alert.

    Example: "1h"
  • thresholdTypeaboveorbeloworabove_exclusiveorbelow_or_equalorequalornot_equal+2 morerequired

    Threshold comparison direction.

    Example: "above"
  • dashboardIdoptionalstringor null

    Dashboard ID for tile-based alerts.

    Example: "65f5e4a3b9e77c001a567890"
  • tileIdoptionalstringor null

    Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.

    Example: "65f5e4a3b9e77c001a901234"
  • savedSearchIdoptionalstringor null

    Saved search ID for saved_search alerts.

    Example: "65f5e4a3b9e77c001a345678"
  • groupByoptionalstringor null

    Group-by key for saved search alerts.

    Example: "ServiceName"
  • chartConfigoptionalAlertLineChartConfigorAlertBarChartConfigorAlertNumberChartConfig

    Chart configuration for inline alerts. Required when source is "inline" and rejected otherwise. Returned on single-alert responses (GET by ID, POST, PUT); the list endpoint omits it.

    3 variants

    One of the following:

    • AlertLineChartConfig
      View AlertLineChartConfig schema →
      3 properties
      • nameoptionalstring

        Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

        Example: "Error Rate Query"
      • whereoptionalstring

        Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

        maxLength: 10000
        Example: "ServiceName:api"
      • whereLanguageoptionalsqlorlucene

        Language of the chart-level "where" filter.

    • AlertBarChartConfig
      View AlertBarChartConfig schema →
      3 properties
      • nameoptionalstring

        Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

        Example: "Error Rate Query"
      • whereoptionalstring

        Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

        maxLength: 10000
        Example: "ServiceName:api"
      • whereLanguageoptionalsqlorlucene

        Language of the chart-level "where" filter.

    • AlertNumberChartConfig
      View AlertNumberChartConfig schema →
      3 properties
      • nameoptionalstring

        Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

        Example: "Error Rate Query"
      • whereoptionalstring

        Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

        maxLength: 10000
        Example: "ServiceName:api"
      • whereLanguageoptionalsqlorlucene

        Language of the chart-level "where" filter.

  • thresholdMaxoptionalnumberor null

    Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.

    Example: 500
  • scheduleOffsetMinutesoptionalintegeror null

    Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).

    minimum: 0
    Example: 2
  • scheduleStartAtoptionalstringor null

    Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.

    format: date-time
    Example: "2026-02-08T10:00:00.000Z"
  • sourceoptionalsaved_searchortileorinline

    Alert source type (tile-based or saved search).

    Example: "tile"
  • channeloptionalAlertChannelWebhook

    First notification channel, mirrored from "channels" for pre-multi-channel clients.

    1 variants

    One of the following:

  • channelsoptionalarray ofAlertChannelWebhook

    All notification channels to trigger when the alert fires or resolves.

    1 variants

    One of the following:

  • nameoptionalstringor null

    Alert name template (Handlebars), rendered as the notification title. When omitted, a default title is generated from the display name, value and threshold.

    Example: "Errors for {{group}} hit {{value}}"
  • displayNameoptionalstringor null

    Display name shown in the alerts list and in notification titles. Defaults to the name of the referenced saved search, dashboard tile, or inline chart when omitted or null.

    maxLength: 512, minLength: 1
    Example: "Checkout error spike"
  • tagsoptionalarray ofstringor null

    Tags for the alert. Defaults to the tags of the referenced saved search or dashboard when omitted or null; inline alerts have no parent to inherit from and default to an empty list.

    maxLength: 32
    Example: ["checkout","p1"]
  • messageoptionalstringor null

    Alert message template.

    Example: "Test Alert Message"
  • noteoptionalstringor null

    Freeform note for the alert. Supports markdown formatting.

    maxLength: 4096, minLength: 1
    Example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
  • numConsecutiveWindowsoptionalintegeror null

    Fire the alert only after its condition has been met for this many consecutive evaluation windows. While the condition is met but fewer than this many consecutive windows have violated, the alert is in the PENDING state.

    minimum: 1
    Example: 3

Response

JSON

200

Successfully updated alert

JSON
  • dataoptionalobject

    The alert object.

    27 properties
    • displayNamestringrequired

      The display name for the alert in the UI. Derived from the saved search name, dashboard tile name, or inline chartConfig name when not explicitly set.

      Example: "Checkout error spike"
    • tagsarray ofstringrequired

      The tags for the alert. Derived from the tags of the referenced saved search or dashboard when not explicitly set; inline alerts default to an empty list.

      Example: ["checkout","p1"]
    • dashboardIdoptionalstringor null

      Dashboard ID for tile-based alerts.

      Example: "65f5e4a3b9e77c001a567890"
    • tileIdoptionalstringor null

      Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.

      Example: "65f5e4a3b9e77c001a901234"
    • savedSearchIdoptionalstringor null

      Saved search ID for saved_search alerts.

      Example: "65f5e4a3b9e77c001a345678"
    • groupByoptionalstringor null

      Group-by key for saved search alerts.

      Example: "ServiceName"
    • chartConfigoptionalAlertLineChartConfigorAlertBarChartConfigorAlertNumberChartConfig

      Chart configuration for inline alerts. Required when source is "inline" and rejected otherwise. Returned on single-alert responses (GET by ID, POST, PUT); the list endpoint omits it.

      3 variants

      One of the following:

      • AlertLineChartConfig
        View AlertLineChartConfig schema →
        3 properties
        • nameoptionalstring

          Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

          Example: "Error Rate Query"
        • whereoptionalstring

          Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

          maxLength: 10000
          Example: "ServiceName:api"
        • whereLanguageoptionalsqlorlucene

          Language of the chart-level "where" filter.

      • AlertBarChartConfig
        View AlertBarChartConfig schema →
        3 properties
        • nameoptionalstring

          Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

          Example: "Error Rate Query"
        • whereoptionalstring

          Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

          maxLength: 10000
          Example: "ServiceName:api"
        • whereLanguageoptionalsqlorlucene

          Language of the chart-level "where" filter.

      • AlertNumberChartConfig
        View AlertNumberChartConfig schema →
        3 properties
        • nameoptionalstring

          Display name for the alert query. Used in notification titles and as an alert-name fallback when the alert itself has no name.

          Example: "Error Rate Query"
        • whereoptionalstring

          Chart-level filter applied on top of every select item's own "where" (combined via AND). Builder variants only; rejected on Raw SQL variants (filter inside the sqlTemplate instead).

          maxLength: 10000
          Example: "ServiceName:api"
        • whereLanguageoptionalsqlorlucene

          Language of the chart-level "where" filter.

    • thresholdoptionalnumber

      Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.

      Example: 100
    • thresholdMaxoptionalnumberor null

      Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.

      Example: 500
    • intervaloptional1mor5mor15mor30mor1hor6h+2 more

      Evaluation interval for the alert.

      Example: "1h"
    • scheduleOffsetMinutesoptionalintegeror null

      Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).

      minimum: 0
      Example: 2
    • scheduleStartAtoptionalstringor null

      Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.

      format: date-time
      Example: "2026-02-08T10:00:00.000Z"
    • sourceoptionalsaved_searchortileorinline

      Alert source type (tile-based or saved search).

      Example: "tile"
    • thresholdTypeoptionalaboveorbeloworabove_exclusiveorbelow_or_equalorequalornot_equal+2 more

      Threshold comparison direction.

      Example: "above"
    • channeloptionalAlertChannelWebhook

      First notification channel, mirrored from "channels" for pre-multi-channel clients.

      1 variants

      One of the following:

    • channelsoptionalarray ofAlertChannelWebhook

      All notification channels to trigger when the alert fires or resolves.

      1 variants

      One of the following:

    • nameoptionalstringor null

      Alert name template (Handlebars), rendered as the notification title. When omitted, a default title is generated from the display name, value and threshold.

      Example: "Errors for {{group}} hit {{value}}"
    • messageoptionalstringor null

      Alert message template.

      Example: "Test Alert Message"
    • noteoptionalstringor null

      Freeform note for the alert. Supports markdown formatting.

      maxLength: 4096, minLength: 1
      Example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
    • numConsecutiveWindowsoptionalintegeror null

      Fire the alert only after its condition has been met for this many consecutive evaluation windows. While the condition is met but fewer than this many consecutive windows have violated, the alert is in the PENDING state.

      minimum: 1
      Example: 3
    • idoptionalstring

      Unique alert identifier.

      Example: "65f5e4a3b9e77c001a123456"
    • stateoptionalALERTorOKorINSUFFICIENT_DATAorDISABLEDorPENDING

      Current alert state.

      Example: "ALERT"
    • teamIdoptionalstring

      Team identifier.

      Example: "65f5e4a3b9e77c001a345678"
    • silencedoptionalobjector null

      Silencing metadata.

      3 properties
      • byoptionalstringor null

        User ID who silenced the alert.

        Example: "65f5e4a3b9e77c001a234567"
      • atoptionalstring

        Silence start timestamp.

        format: date-time
        Example: "2026-03-19T08:00:00.000Z"
      • untiloptionalstring

        Silence end timestamp.

        format: date-time
        Example: "2026-03-20T08:00:00.000Z"
    • executionErrorsoptionalarray ofobjector null

      Errors recorded during the most recent alert execution, if any.

      3 properties
      • timestampstringrequired

        When the error occurred.

        format: date-time
        Example: "2026-04-17T12:00:00.000Z"
      • typeQUERY_ERRORorQUERY_TIMEOUTorWEBHOOK_ERRORorINVALID_ALERTorUNKNOWNrequired

        Category of the error.

        Example: "QUERY_ERROR"
      • messagestringrequired

        Human-readable error message.

        Example: "Query timed out after 30s"
    • createdAtoptionalstringor null

      Creation timestamp.

      format: date-time
      Example: "2023-01-01T00:00:00.000Z"
    • updatedAtoptionalstringor null

      Last update timestamp.

      format: date-time
      Example: "2023-01-01T00:00:00.000Z"
Navigation