Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

ClickStack: Update Alert

Beta
PUT/v1/organizations/{organizationId}/services/{serviceId}/clickstack/alerts/{clickStackAlertId}
API playground

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

ClickStack: Updates an existing alert

Permission

The API key must have the control-plane:service:manage-clickstack-api permission.

Authorizations

Path parameters

  • organizationIdstringrequired

    ID of the organization that owns the service.

    format: uuid
  • serviceIdstringrequired

    ID of the ClickStack service.

    format: uuid
  • clickStackAlertIdstringrequired

    ClickStack 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
  • interval30sor1mor5mor15mor30mor1h+3 morerequired

    Evaluation interval for the alert. 30s requires the 30s alert interval feature to be enabled for your team. Anomaly alerts (detectionMode "anomaly") support only 5m, 15m, 30m, and 1h; other intervals are rejected with 400.

    Example: "1h"
  • thresholdTypeaboveorbeloworabove_exclusiveorbelow_or_equalorequalornot_equal+2 morerequired

    Threshold comparison direction.

    Example: "above"
  • dashboardIdoptionalstring | null

    Dashboard ID for tile-based alerts.

    Example: "65f5e4a3b9e77c001a567890"
  • tileIdoptionalstring | null

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

    Example: "65f5e4a3b9e77c001a901234"
  • savedSearchIdoptionalstring | null

    Saved search ID for saved_search alerts.

    Example: "65f5e4a3b9e77c001a345678"
  • groupByoptionalstring | null

    Group-by key for saved search alerts.

    Example: "ServiceName"
  • chartConfigoptionalClickStackAlertLineChartConfigorClickStackAlertBarChartConfigorClickStackAlertStackedLineChartConfigorClickStackAlertNumberChartConfig
    4 variants

    One of the following:

    • ClickStackAlertLineChartConfig
    • ClickStackAlertBarChartConfig
    • ClickStackAlertStackedLineChartConfig
    • ClickStackAlertNumberChartConfig
  • thresholdMaxoptionalnumber | null

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

    Example: 500
  • scheduleOffsetMinutesoptionalinteger | null

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

    Example: 2
  • scheduleStartAtoptionalstring | 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"
  • channeloptionalClickStackAlertChannelEmailorClickStackAlertChannelWebhook
    2 variants

    One of the following:

    • ClickStackAlertChannelEmail
      2 properties
      • typewebhookoremailrequired

        Channel type. Must be "email" for email alerts.

      • emailRecipientsarray ofstringrequired

        Email recipients for email alerts.

    • ClickStackAlertChannelWebhook
      5 properties
      • typewebhookoremailrequired

        Channel type. Must be "webhook" for webhook alerts.

      • webhookIdstringrequired

        Webhook destination ID.

        Example: "65f5e4a3b9e77c001a789012"
      • webhookServiceoptionalstring | null

        Webhook service type (e.g., slack_api).

        Example: "slack_api"
      • slackChannelIdoptionalstring | null

        Slack channel ID for Slack webhooks.

        Example: "C01ABCDEF23"
      • severityoptionalcriticalorerrororwarningorinfo

        Severity label used by PagerDuty API webhooks.

  • channelsoptionalarray ofClickStackAlertChannelEmailorClickStackAlertChannelWebhook

    Notification channels to trigger when the alert fires or resolves. Between 1 and 10 channels; duplicates are rejected.

    2 variants

    One of the following:

    • ClickStackAlertChannelEmail
      2 properties
      • typewebhookoremailrequired

        Channel type. Must be "email" for email alerts.

      • emailRecipientsarray ofstringrequired

        Email recipients for email alerts.

    • ClickStackAlertChannelWebhook
      5 properties
      • typewebhookoremailrequired

        Channel type. Must be "webhook" for webhook alerts.

      • webhookIdstringrequired

        Webhook destination ID.

        Example: "65f5e4a3b9e77c001a789012"
      • webhookServiceoptionalstring | null

        Webhook service type (e.g., slack_api).

        Example: "slack_api"
      • slackChannelIdoptionalstring | null

        Slack channel ID for Slack webhooks.

        Example: "C01ABCDEF23"
      • severityoptionalcriticalorerrororwarningorinfo

        Severity label used by PagerDuty API webhooks.

  • nameoptionalstring | 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}}"
  • displayNameoptionalstring | 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.

    Example: "Checkout error spike"
  • tagsoptionalarray ofstring

    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.

    Example: ["checkout","p1"]
  • messageoptionalstring | null

    Alert message template.

    Example: "Test Alert Message"
  • noteoptionalstring | null

    Freeform note for the alert. Supports markdown formatting.

    Example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
  • numConsecutiveWindowsoptionalinteger | 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.

    Example: 3

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    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"]
    • dashboardIdoptionalstring | null

      Dashboard ID for tile-based alerts.

      Example: "65f5e4a3b9e77c001a567890"
    • tileIdoptionalstring | null

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

      Example: "65f5e4a3b9e77c001a901234"
    • savedSearchIdoptionalstring | null

      Saved search ID for saved_search alerts.

      Example: "65f5e4a3b9e77c001a345678"
    • groupByoptionalstring | null

      Group-by key for saved search alerts.

      Example: "ServiceName"
    • chartConfigoptionalClickStackAlertLineChartConfigorClickStackAlertBarChartConfigorClickStackAlertStackedLineChartConfigorClickStackAlertNumberChartConfig
      4 variants

      One of the following:

      • ClickStackAlertLineChartConfig
      • ClickStackAlertBarChartConfig
      • ClickStackAlertStackedLineChartConfig
      • ClickStackAlertNumberChartConfig
    • thresholdoptionalnumber

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

      Example: 100
    • thresholdMaxoptionalnumber | null

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

      Example: 500
    • intervaloptional30sor1mor5mor15mor30mor1h+3 more

      Evaluation interval for the alert. 30s requires the 30s alert interval feature to be enabled for your team. Anomaly alerts (detectionMode "anomaly") support only 5m, 15m, 30m, and 1h; other intervals are rejected with 400.

      Example: "1h"
    • scheduleOffsetMinutesoptionalinteger | null

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

      Example: 2
    • scheduleStartAtoptionalstring | 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"
    • channeloptionalClickStackAlertChannelEmailorClickStackAlertChannelWebhook
      2 variants

      One of the following:

      • ClickStackAlertChannelEmail
        2 properties
        • typewebhookoremailrequired

          Channel type. Must be "email" for email alerts.

        • emailRecipientsarray ofstringrequired

          Email recipients for email alerts.

      • ClickStackAlertChannelWebhook
        5 properties
        • typewebhookoremailrequired

          Channel type. Must be "webhook" for webhook alerts.

        • webhookIdstringrequired

          Webhook destination ID.

          Example: "65f5e4a3b9e77c001a789012"
        • webhookServiceoptionalstring | null

          Webhook service type (e.g., slack_api).

          Example: "slack_api"
        • slackChannelIdoptionalstring | null

          Slack channel ID for Slack webhooks.

          Example: "C01ABCDEF23"
        • severityoptionalcriticalorerrororwarningorinfo

          Severity label used by PagerDuty API webhooks.

    • channelsoptionalarray ofClickStackAlertChannelEmailorClickStackAlertChannelWebhook

      Notification channels to trigger when the alert fires or resolves. Between 1 and 10 channels; duplicates are rejected.

      2 variants

      One of the following:

      • ClickStackAlertChannelEmail
        2 properties
        • typewebhookoremailrequired

          Channel type. Must be "email" for email alerts.

        • emailRecipientsarray ofstringrequired

          Email recipients for email alerts.

      • ClickStackAlertChannelWebhook
        5 properties
        • typewebhookoremailrequired

          Channel type. Must be "webhook" for webhook alerts.

        • webhookIdstringrequired

          Webhook destination ID.

          Example: "65f5e4a3b9e77c001a789012"
        • webhookServiceoptionalstring | null

          Webhook service type (e.g., slack_api).

          Example: "slack_api"
        • slackChannelIdoptionalstring | null

          Slack channel ID for Slack webhooks.

          Example: "C01ABCDEF23"
        • severityoptionalcriticalorerrororwarningorinfo

          Severity label used by PagerDuty API webhooks.

    • nameoptionalstring | 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}}"
    • messageoptionalstring | null

      Alert message template.

      Example: "Test Alert Message"
    • noteoptionalstring | null

      Freeform note for the alert. Supports markdown formatting.

      Example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
    • numConsecutiveWindowsoptionalinteger | 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.

      Example: 3
    • idoptionalstring

      Unique alert identifier.

      Example: "65f5e4a3b9e77c001a123456"
    • stateoptionalALERTorOKorINSUFFICIENT_DATAorDISABLEDorPENDING

      Current alert state.

      Example: "ALERT"
    • teamIdoptionalstring

      Team identifier.

      Example: "65f5e4a3b9e77c001a345678"
    • silencedoptionalClickStackAlertSilencedornull
      2 variants

      One of the following:

      • ClickStackAlertSilenced
        3 properties
        • byoptionalstring | 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"
      • null
    • executionErrorsoptionalarray ofobject

      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"
    • createdAtoptionalstring | null

      Creation timestamp.

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

      Last update timestamp.

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