Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

ClickStack: List Alerts

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

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

ClickStack: Retrieves alerts for the authenticated team (paginated). Results are capped at limit (default and maximum 1000). When totalCount exceeds the number of returned items, page with limit/offset to retrieve them all. Optional filters narrow the result set, and totalCount counts only the matching alerts.

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

Query parameters

  • limitoptionalinteger

    Maximum number of results to return.

    maximum: 1000, minimum: 1
    Default: 1000
  • offsetoptionalinteger

    Number of results to skip before returning.

    minimum: 0
    Default: 0
  • tagoptionalarray ofstring

    Only return alerts that have any of the given tags. Repeat the parameter to pass several tags. Matches the tags stored on the alert, not tags inherited from the linked dashboard or saved search.

  • searchoptionalstring

    Only return alerts whose display name contains this text (case-insensitive). Matches the display name stored on the alert, not a name derived from the linked dashboard or saved search.

    maxLength: 512
  • sourceoptionalarray ofstring

    Only return alerts of any of the given sources. Repeat the parameter to pass several sources.

  • stateoptionalarray ofstring

    Only return alerts in any of the given states. Repeat the parameter to pass several states.

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalarray ofobject
    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"