alerts

Creates, updates, deletes, gets or lists an alerts resource.

Overview

Name	`alerts`
Type	Resource
Id	`clickhouse.clickstack.alerts`

Fields

The following fields are returned by SELECT queries:

get
list

Name	Datatype	Description
`id`	`string`	Unique alert identifier. (example: 65f5e4a3b9e77c001a123456)
`name`	`string`	Human-friendly alert name. (example: Test Alert)
`dashboard_id`	`string`	Dashboard ID for tile-based alerts. (example: 65f5e4a3b9e77c001a567890) (wire: dashboardId)
`saved_search_id`	`string`	Saved search ID for saved_search alerts. (example: 65f5e4a3b9e77c001a345678) (wire: savedSearchId)
`team_id`	`string`	Team identifier. (example: 65f5e4a3b9e77c001a345678) (wire: teamId)
`tile_id`	`string`	Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile. (example: 65f5e4a3b9e77c001a901234) (wire: tileId)
`channel`	`object`
`created_at`	`string (date-time)`	Creation timestamp. (example: 2023-01-01T00:00:00.000Z) (wire: createdAt)
`execution_errors`	`array`	Errors recorded during the most recent alert execution, if any. (wire: executionErrors)
`group_by`	`string`	Group-by key for saved search alerts. (example: ServiceName) (wire: groupBy)
`interval`	`string`	Evaluation interval for the alert. (1m, 5m, 15m, 30m, 1h, 6h, 12h, 1d) (example: 1h)
`message`	`string`	Alert message template. (example: Test Alert Message)
`note`	`string`	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).)
`num_consecutive_windows`	`integer`	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. (wire: numConsecutiveWindows)
`schedule_offset_minutes`	`integer`	Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC). (wire: scheduleOffsetMinutes)
`schedule_start_at`	`string (date-time)`	Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval. (example: 2026-02-08T10:00:00.000Z) (wire: scheduleStartAt)
`silenced`	`object`
`source`	`string`	Alert source type (tile-based or saved search). (saved_search, tile) (example: tile)
`state`	`string`	Current alert state. (ALERT, OK, INSUFFICIENT_DATA, DISABLED, PENDING) (example: ALERT)
`threshold`	`number`	Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.
`threshold_max`	`number`	Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold. (wire: thresholdMax)
`threshold_type`	`string`	Threshold comparison direction. (above, below, above_exclusive, below_or_equal, equal, not_equal, between, not_between) (example: above) (wire: thresholdType)
`updated_at`	`string (date-time)`	Last update timestamp. (example: 2023-01-01T00:00:00.000Z) (wire: updatedAt)

Name	Datatype	Description
`id`	`string`	Unique alert identifier. (example: 65f5e4a3b9e77c001a123456)
`name`	`string`	Human-friendly alert name. (example: Test Alert)
`dashboard_id`	`string`	Dashboard ID for tile-based alerts. (example: 65f5e4a3b9e77c001a567890) (wire: dashboardId)
`saved_search_id`	`string`	Saved search ID for saved_search alerts. (example: 65f5e4a3b9e77c001a345678) (wire: savedSearchId)
`team_id`	`string`	Team identifier. (example: 65f5e4a3b9e77c001a345678) (wire: teamId)
`tile_id`	`string`	Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile. (example: 65f5e4a3b9e77c001a901234) (wire: tileId)
`channel`	`object`
`created_at`	`string (date-time)`	Creation timestamp. (example: 2023-01-01T00:00:00.000Z) (wire: createdAt)
`execution_errors`	`array`	Errors recorded during the most recent alert execution, if any. (wire: executionErrors)
`group_by`	`string`	Group-by key for saved search alerts. (example: ServiceName) (wire: groupBy)
`interval`	`string`	Evaluation interval for the alert. (1m, 5m, 15m, 30m, 1h, 6h, 12h, 1d) (example: 1h)
`message`	`string`	Alert message template. (example: Test Alert Message)
`note`	`string`	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).)
`num_consecutive_windows`	`integer`	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. (wire: numConsecutiveWindows)
`schedule_offset_minutes`	`integer`	Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC). (wire: scheduleOffsetMinutes)
`schedule_start_at`	`string (date-time)`	Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval. (example: 2026-02-08T10:00:00.000Z) (wire: scheduleStartAt)
`silenced`	`object`
`source`	`string`	Alert source type (tile-based or saved search). (saved_search, tile) (example: tile)
`state`	`string`	Current alert state. (ALERT, OK, INSUFFICIENT_DATA, DISABLED, PENDING) (example: ALERT)
`threshold`	`number`	Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.
`threshold_max`	`number`	Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold. (wire: thresholdMax)
`threshold_type`	`string`	Threshold comparison direction. (above, below, above_exclusive, below_or_equal, equal, not_equal, between, not_between) (example: above) (wire: thresholdType)
`updated_at`	`string (date-time)`	Last update timestamp. (example: 2023-01-01T00:00:00.000Z) (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`service_id`, `click_stack_alert_id`, `organization_id`		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a specific alert by ID
`list`	`select`	`service_id`, `organization_id`	`limit`, `offset`	This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> 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.
`create`	`insert`	`service_id`, `organization_id`		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Creates a new alert
`update`	`update`	`service_id`, `click_stack_alert_id`, `organization_id`		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Updates an existing alert
`delete`	`delete`	`service_id`, `click_stack_alert_id`, `organization_id`		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Deletes an alert

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`click_stack_alert_id`	`string`	ClickStack Alert ID (wire: clickStackAlertId)
`organization_id`	`string`	ClickHouse Cloud organization ID. Resolved from the CLICKHOUSE_ORG_ID environment variable when it is set (x-stackQL-envVar); otherwise it must be supplied on every query as WHERE organization_id = <uuid>. A WHERE value always takes precedence over the environment. (x-stackQL-envVar: CLICKHOUSE_ORG_ID)
`service_id`	`string (uuid)`	ID of the ClickStack service. (wire: serviceId)
`limit`	`integer`	Maximum number of results to return.
`offset`	`integer`	Number of results to skip before returning.

`SELECT` examples

get
list

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. ClickStack: Retrieves a specific alert by ID

SELECT
id,
name,
dashboard_id,
saved_search_id,
team_id,
tile_id,
channel,
created_at,
execution_errors,
group_by,
interval,
message,
note,
num_consecutive_windows,
schedule_offset_minutes,
schedule_start_at,
silenced,
source,
state,
threshold,
threshold_max,
threshold_type,
updated_at
FROM clickhouse.clickstack.alerts
WHERE service_id = '{{ service_id }}' -- required
AND click_stack_alert_id = '{{ click_stack_alert_id }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
;

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.

SELECT
id,
name,
dashboard_id,
saved_search_id,
team_id,
tile_id,
channel,
created_at,
execution_errors,
group_by,
interval,
message,
note,
num_consecutive_windows,
schedule_offset_minutes,
schedule_start_at,
silenced,
source,
state,
threshold,
threshold_max,
threshold_type,
updated_at
FROM clickhouse.clickstack.alerts
WHERE service_id = '{{ service_id }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
AND limit = '{{ limit }}'
AND offset = '{{ offset }}'
;

`INSERT` examples

create
Manifest

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. ClickStack: Creates a new alert

INSERT INTO clickhouse.clickstack.alerts (
dashboard_id,
tile_id,
saved_search_id,
group_by,
threshold,
threshold_max,
interval,
schedule_offset_minutes,
schedule_start_at,
source,
threshold_type,
channel,
name,
message,
note,
num_consecutive_windows,
service_id,
organization_id
)
SELECT 
'{{ dashboard_id }}',
'{{ tile_id }}',
'{{ saved_search_id }}',
'{{ group_by }}',
{{ threshold }},
{{ threshold_max }},
'{{ interval }}',
{{ schedule_offset_minutes }},
'{{ schedule_start_at }}',
'{{ source }}',
'{{ threshold_type }}',
'{{ channel }}',
'{{ name }}',
'{{ message }}',
'{{ note }}',
{{ num_consecutive_windows }},
'{{ service_id }}',
'{{ organization_id }}'
RETURNING
request_id,
result,
status
;

# Description fields are for documentation purposes
- name: alerts
props:
  - name: service_id
    value: "{{ service_id }}"
    description: Required parameter for the alerts resource.
  - name: organization_id
    value: "{{ organization_id }}"
    description: Required parameter for the alerts resource.
  - name: dashboard_id
    value: "{{ dashboard_id }}"
    description: |
      Dashboard ID for tile-based alerts.
  - name: tile_id
    value: "{{ tile_id }}"
    description: |
      Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.
  - name: saved_search_id
    value: "{{ saved_search_id }}"
    description: |
      Saved search ID for saved_search alerts.
  - name: group_by
    value: "{{ group_by }}"
    description: |
      Group-by key for saved search alerts.
  - name: threshold
    value: {{ threshold }}
    description: |
      Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.
  - name: threshold_max
    value: {{ threshold_max }}
    description: |
      Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.
  - name: interval
    value: "{{ interval }}"
    description: |
      Evaluation interval for the alert.
    valid_values: ['1m', '5m', '15m', '30m', '1h', '6h', '12h', '1d']
  - name: schedule_offset_minutes
    value: {{ schedule_offset_minutes }}
    description: |
      Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).
  - name: schedule_start_at
    value: "{{ schedule_start_at }}"
    description: |
      Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.
  - name: source
    value: "{{ source }}"
    description: |
      Alert source type (tile-based or saved search).
    valid_values: ['saved_search', 'tile']
  - name: threshold_type
    value: "{{ threshold_type }}"
    description: |
      Threshold comparison direction.
    valid_values: ['above', 'below', 'above_exclusive', 'below_or_equal', 'equal', 'not_equal', 'between', 'not_between']
  - name: channel
    value:
      type: "{{ type }}"
      emailRecipients:
        - "{{ emailRecipients }}"
      webhookId: "{{ webhookId }}"
      webhookService: "{{ webhookService }}"
      slackChannelId: "{{ slackChannelId }}"
      severity: "{{ severity }}"
  - name: name
    value: "{{ name }}"
    description: |
      Human-friendly alert name.
  - name: message
    value: "{{ message }}"
    description: |
      Alert message template.
  - name: note
    value: "{{ note }}"
    description: |
      Freeform note for the alert. Supports markdown formatting.
  - name: num_consecutive_windows
    value: {{ num_consecutive_windows }}
    description: |
      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.

`UPDATE` examples

update

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. ClickStack: Updates an existing alert

UPDATE clickhouse.clickstack.alerts
SET 
dashboard_id = '{{ dashboard_id }}',
tile_id = '{{ tile_id }}',
saved_search_id = '{{ saved_search_id }}',
group_by = '{{ group_by }}',
threshold = {{ threshold }},
threshold_max = {{ threshold_max }},
interval = '{{ interval }}',
schedule_offset_minutes = {{ schedule_offset_minutes }},
schedule_start_at = '{{ schedule_start_at }}',
source = '{{ source }}',
threshold_type = '{{ threshold_type }}',
channel = '{{ channel }}',
name = '{{ name }}',
message = '{{ message }}',
note = '{{ note }}',
num_consecutive_windows = {{ num_consecutive_windows }}
WHERE 
service_id = '{{ service_id }}' --required
AND click_stack_alert_id = '{{ click_stack_alert_id }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
RETURNING
request_id,
result,
status;

`DELETE` examples

delete

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. ClickStack: Deletes an alert

DELETE FROM clickhouse.clickstack.alerts
WHERE service_id = '{{ service_id }}' --required
AND click_stack_alert_id = '{{ click_stack_alert_id }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​