Alert

View as Markdown

A SQL alert. An alert runs a query on a schedule, evaluates the result against a condition, and notifies users or notification destinations when the condition is met.

Get an alertGET /api/2.0/alerts/{id}List alertsGET /api/2.0/alertsCreate an alertPOST /api/2.0/alertsUpdate an alertPATCH /api/2.0/alerts/{id}Delete an alert (legacy TrashAlert)DELETE /api/2.0/alerts/{id}

Alert object

A SQL alert. An alert runs a query on a schedule, evaluates the result against a condition, and notifies users or notification destinations when the condition is met.

idstringOutput onlyIDImmutable

The canonical identifier of the alert to retrieve information about.

Example: 1927647905808833

display_namestring

The display name of the alert.

Example: Example alert

owner_user_namestringOutput only

The owner's username. This field is set to "Unavailable" if the user has been deleted.

Example: user@acme.com

create_timestringOutput only

The timestamp indicating when the alert was created.

update_timestringOutput only

The timestamp indicating when the alert was updated.

parent_pathstring

The workspace path of the folder containing the alert. Can only be set on create, and cannot be updated.

Example: /Users/user@acme.com

query_textstring

Text of the query to be run.

Example: SELECT 1

warehouse_idstring

ID of the SQL warehouse attached to the alert.

Example: a7066a8ef796be84

run_as_user_namestringDeprecated

Deprecated: Use run_as field instead. This field will be removed in a future release. The run as username or application ID of service principal. On Create and Update, this field can be set to application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: user@acme.com

evaluationobject

Condition evaluated against the query result, and who is notified when it is met.

Show child attributesHide child attributes

sourceobject

Source column from result to use to evaluate alert

Show child attributesHide child attributes

namestring

Name of the column in the query result.

displaystring

Label for the column in notifications. Defaults to name.

aggregationstring

Aggregation applied to the column across all rows of the query result: SUM, COUNT, COUNT_DISTINCT, AVG, MEDIAN, MIN, MAX or STDDEV. If not set, the value in the first row is used, which is equivalent to using First row in the UI.

Values:

• SUM
• COUNT
• COUNT_DISTINCT
• AVG
• MEDIAN
• MIN
• MAX
• STDDEV

comparison_operatorstring

Operator used for comparison in alert evaluation. The alert is triggered when the comparison of the source value with the threshold is true. IS_NULL and IS_NOT_NULL take no threshold.

Values:

• LESS_THAN
• GREATER_THAN
• EQUAL
• NOT_EQUAL
• GREATER_THAN_OR_EQUAL
• LESS_THAN_OR_EQUAL
• IS_NULL
• IS_NOT_NULL

thresholdobject

Threshold to compare the source column against, either another column or a fixed value. Not needed when comparison_operator is IS_NULL or IS_NOT_NULL.

Show child attributesHide child attributes

columnobject

Compare the source against another column of the query result.

Show child attributesHide child attributes

namestring

Name of the column in the query result.

displaystring

Label for the column in notifications. Defaults to name.

aggregationstring

Aggregation applied to the column across all rows of the query result: SUM, COUNT, COUNT_DISTINCT, AVG, MEDIAN, MIN, MAX or STDDEV. If not set, the value in the first row is used, which is equivalent to using First row in the UI.

Values:

• SUM
• COUNT
• COUNT_DISTINCT
• AVG
• MEDIAN
• MIN
• MAX
• STDDEV

valueobject

Compare the source against a fixed value.

Show child attributesHide child attributes

string_valuestring

String threshold, for string or timestamp columns.

Example: foo

double_valuedouble

Numeric threshold, for numeric columns.

Example: 1.25

bool_valueboolean

Boolean threshold, for boolean columns.

Example: true

notificationobject

User or Notification Destination to notify when alert is triggered.

Show child attributesHide child attributes

subscriptionsarray of objectUnordered list

Users and notification destinations that receive notifications.

Show child attributesHide child attributes

user_emailstring

Email address of the workspace user to notify.

destination_idstring

ID of the notification destination to notify, as returned by the Notification Destinations API.

Example: 8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b

retrigger_secondsint32

Number of seconds an alert waits after being triggered before it is allowed to send another notification. If set to 0 or omitted, the alert will not send any further notifications after the first trigger Setting this value to 1 allows the alert to send a notification on every evaluation where the condition is met, effectively making it always retrigger for notification purposes.

Example: 0

notify_on_okboolean

Whether to notify alert subscribers when alert returns back to normal.

statestringOutput only

Latest state of alert evaluation: TRIGGERED when the condition was met, OK when it was not, and ERROR when the evaluation failed.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

last_evaluated_atstringOutput only

Timestamp of the last evaluation.

empty_result_statestring

Alert state if result is empty. If not set, an empty result sets the state to ERROR. Please avoid setting this field to be UNKNOWN because UNKNOWN state is planned to be deprecated.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

scheduleobject

Schedule on which the alert runs its query and evaluates the condition.

Show child attributesHide child attributes

quartz_cron_schedulestring

A cron expression using quartz syntax that specifies the schedule for this alert. Should use the quartz format described here: http://www.quartz-scheduler.org/documentation/quartz-2.1.7/tutorials/tutorial-lesson-06.html

Example: 0 0 9 * * ?

timezone_idstring

A Java timezone id. The schedule will be resolved using this timezone. This will be combined with the quartz_cron_schedule to determine the schedule. See https://docs.databricks.com/sql/language-manual/sql-ref-syntax-aux-conf-mgmt-set-timezone.html for details.

Example: America/Los_Angeles

pause_statusstring

Indicates whether this schedule is paused. While paused, the alert is not evaluated.

Default: UNPAUSED

Values:

• UNPAUSED
• PAUSED

lifecycle_statestringOutput only

Indicates whether the alert is active (ACTIVE) or has been moved to the trash (DELETED).

Values:

• ACTIVE
• DELETED

custom_summarystring

Custom summary for the alert, used as the notification subject. Interpreted according to custom_template_format.

custom_descriptionstring

Custom description for the alert, used as the notification body. Interpreted according to custom_template_format. The available template variables are listed at https://docs.databricks.com/aws/en/sql/user/alerts/create#notification-templates.

run_asobject

Specifies the identity that will be used to run the alert. This field allows you to configure alerts to run as a specific user or service principal.

• For user identity: Set user_name to the email of an active workspace user. Users can only set this to their own email.
• For service principal: Set service_principal_name to the application ID. Requires the servicePrincipal/user role. If not specified, the alert will run as the request user.

Show child attributesHide child attributes

user_namestring

The email of an active workspace user. Can only set this field to their own email.

Example: user@databricks.com

service_principal_namestring

Application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: 692bc6d0-ffa3-11ed-be56-0242ac120002

effective_run_asobjectOutput only

The actual identity that will be used to execute the alert. This is an output-only field that shows the resolved run-as identity after applying permissions and defaults.

Show child attributesHide child attributes

user_namestring

The email of an active workspace user. Can only set this field to their own email.

Example: user@databricks.com

service_principal_namestring

Application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: 692bc6d0-ffa3-11ed-be56-0242ac120002

parametersarray of objectBetaUnordered list

A list of parameters to pass into the alert SQL query statement containing parameter markers. Static values only.

Reference a parameter in the query text as :name. Each parameter must have a unique, non-empty name. Each parameter consists of a name, a value, and optionally a type. To represent a NULL value, the value field may be omitted or set to null explicitly. If the type field is omitted, the value is interpreted as a string.

If the type is given, parameters will be checked for type correctness according to the given type. A value is correct if the provided string can be converted to the requested type using the cast function. The exact semantics are described in the section cast function of the SQL language reference.

Show child attributesHide child attributes

namestringBeta

The name of the parameter. Reference it in the query text as :name. Required, must be non-empty, and must be unique across the alert's parameters.

Example: region

valuestringBeta

The value bound to the parameter, represented as a string. If omitted, the value is interpreted as NULL.

Example: US

typestringBeta

The SQL data type of the parameter, for example STRING, INT, or DECIMAL(10, 2). If no type is given the type is assumed to be STRING. Complex types such as ARRAY, MAP, and STRUCT are not supported.

Example: STRING

custom_template_formatstringPublic Preview

The format used to interpret the custom_summary and custom_description templates.

HTML treats both templates as HTML with Mustache {{VARIABLE_NAME}} placeholders. MARKDOWN treats them as Markdown with allowlisted @VARIABLE_NAME placeholders and converts them to the format each notification destination expects, so a single template renders correctly in email, Slack, and Microsoft Teams.

When unset, the API applies no default. Responses omit the field unless a format is stored, and a template with no format is rendered as HTML.

Values:

• HTML
• MARKDOWN

View as Markdown

The Alert object

{
  "create_time": "2025-03-15T10:00:00Z",
  "custom_description": "<p>{{ALERT_COLUMN}} is {{QUERY_RESULT_VALUE}}, above the threshold of {{ALERT_THRESHOLD}}.</p>",
  "custom_summary": "{{ALERT_NAME}} is {{ALERT_STATUS}}",
  "custom_template_format": "HTML",
  "display_name": "Failed orders above threshold",
  "effective_run_as": {
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "OK",
    "last_evaluated_at": "2025-03-16T09:00:12Z",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 3600,
      "subscriptions": [
        {
          "user_email": "user@example.com"
        },
        {
          "destination_id": "8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "Failed orders",
      "name": "failed_orders"
    },
    "state": "TRIGGERED",
    "threshold": {
      "value": {
        "double_value": 100
      }
    }
  },
  "id": "1927647905808833",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@example.com",
  "parameters": [
    {
      "name": "region",
      "type": "STRING",
      "value": "US"
    }
  ],
  "parent_path": "/Users/user@example.com",
  "query_text": "SELECT region, failed_orders FROM main.sales.order_health WHERE region = :region",
  "run_as": {
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 * * * ?",
    "timezone_id": "America/Los_Angeles"
  },
  "update_time": "2025-03-15T10:00:00Z",
  "warehouse_id": "a7066a8ef796be84"
}

Get an alert GA

GET /api/2.0/alerts/{id}

Gets an alert.

API scopes: alerts

Parameters

idstringRequiredpath

ID of the alert to retrieve, as returned in the alert's id field.

Example: 1927647905808833

Response

Returns the Alert object.

View as Markdown

Response

{
  "create_time": "2025-03-15T10:00:00Z",
  "custom_description": "<p>{{ALERT_COLUMN}} is {{QUERY_RESULT_VALUE}}, above the threshold of {{ALERT_THRESHOLD}}.</p>",
  "custom_summary": "{{ALERT_NAME}} is {{ALERT_STATUS}}",
  "custom_template_format": "HTML",
  "display_name": "Failed orders above threshold",
  "effective_run_as": {
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "OK",
    "last_evaluated_at": "2025-03-16T09:00:12Z",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 3600,
      "subscriptions": [
        {
          "user_email": "user@example.com"
        },
        {
          "destination_id": "8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "Failed orders",
      "name": "failed_orders"
    },
    "state": "TRIGGERED",
    "threshold": {
      "value": {
        "double_value": 100
      }
    }
  },
  "id": "1927647905808833",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@example.com",
  "parameters": [
    {
      "name": "region",
      "type": "STRING",
      "value": "US"
    }
  ],
  "parent_path": "/Users/user@example.com",
  "query_text": "SELECT region, failed_orders FROM main.sales.order_health WHERE region = :region",
  "run_as": {
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 * * * ?",
    "timezone_id": "America/Los_Angeles"
  },
  "update_time": "2025-03-15T10:00:00Z",
  "warehouse_id": "a7066a8ef796be84"
}

List alerts GA

GET /api/2.0/alerts

Gets a list of alerts accessible to the user, ordered by creation time.

API scopes: alerts

Parameters

page_tokenstringquery

Page token returned as next_page_token by a previous call. Omit it to retrieve the first page.

page_sizeint32<= 100query

Maximum number of alerts to return per page. Values above 100 are coerced to 100.

Default: 20

Response

Returns a list of Alert objects.

View as Markdown

Response

{
  "alerts": [
    {
      "create_time": "2025-03-15T10:00:00Z",
      "custom_description": "<p>{{ALERT_COLUMN}} is {{QUERY_RESULT_VALUE}}, above the threshold of {{ALERT_THRESHOLD}}.</p>",
      "custom_summary": "{{ALERT_NAME}} is {{ALERT_STATUS}}",
      "custom_template_format": "HTML",
      "display_name": "Failed orders above threshold",
      "effective_run_as": {
        "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
      },
      "evaluation": {
        "comparison_operator": "GREATER_THAN",
        "empty_result_state": "OK",
        "last_evaluated_at": "2025-03-16T09:00:12Z",
        "notification": {
          "notify_on_ok": true,
          "retrigger_seconds": 3600,
          "subscriptions": [
            {
              "user_email": "user@example.com"
            },
            {
              "destination_id": "8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b"
            }
          ]
        },
        "source": {
          "aggregation": "SUM",
          "display": "Failed orders",
          "name": "failed_orders"
        },
        "state": "TRIGGERED",
        "threshold": {
          "value": {
            "double_value": 100
          }
        }
      },
      "id": "1927647905808833",
      "lifecycle_state": "ACTIVE",
      "owner_user_name": "user@example.com",
      "parameters": [
        {
          "name": "region",
          "type": "STRING",
          "value": "US"
        }
      ],
      "query_text": "SELECT region, failed_orders FROM main.sales.order_health WHERE region = :region",
      "run_as": {
        "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
      },
      "schedule": {
        "pause_status": "UNPAUSED",
        "quartz_cron_schedule": "0 0 * * * ?",
        "timezone_id": "America/Los_Angeles"
      },
      "update_time": "2025-03-15T10:00:00Z",
      "warehouse_id": "a7066a8ef796be84"
    },
    {
      "create_time": "2025-03-15T09:00:00Z",
      "display_name": "Daily revenue below target",
      "effective_run_as": {
        "user_name": "user@example.com"
      },
      "evaluation": {
        "comparison_operator": "LESS_THAN",
        "last_evaluated_at": "2025-03-16T09:00:05Z",
        "notification": {
          "subscriptions": [
            {
              "user_email": "user@example.com"
            }
          ]
        },
        "source": {
          "name": "revenue"
        },
        "state": "OK",
        "threshold": {
          "value": {
            "double_value": 50000
          }
        }
      },
      "id": "1927647905808834",
      "lifecycle_state": "ACTIVE",
      "owner_user_name": "user@example.com",
      "query_text": "SELECT sum(amount) AS revenue FROM main.sales.orders WHERE order_date = current_date() - 1",
      "schedule": {
        "pause_status": "UNPAUSED",
        "quartz_cron_schedule": "0 0 9 * * ?",
        "timezone_id": "UTC"
      },
      "update_time": "2025-03-15T09:00:00Z",
      "warehouse_id": "a7066a8ef796be84"
    }
  ],
  "next_page_token": "CiAxOTI3NjQ3OTA1ODA4ODM0"
}

Create an alert GA

POST /api/2.0/alerts

Creates an alert that runs query_text on the given schedule and evaluates the result against the configured condition.

API scopes: alerts

Request body

display_namestringRequired

The display name of the alert.

Example: Example alert

parent_pathstring

The workspace path of the folder containing the alert. Can only be set on create, and cannot be updated.

Example: /Users/user@acme.com

query_textstringRequired

Text of the query to be run.

Example: SELECT 1

warehouse_idstringRequired

ID of the SQL warehouse attached to the alert.

Example: a7066a8ef796be84

run_as_user_namestringDeprecated

Deprecated: Use run_as field instead. This field will be removed in a future release. The run as username or application ID of service principal. On Create and Update, this field can be set to application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: user@acme.com

evaluationobjectRequired

Condition evaluated against the query result, and who is notified when it is met.

Show child attributesHide child attributes

sourceobjectRequired

Source column from result to use to evaluate alert

Show child attributesHide child attributes

namestringRequired

Name of the column in the query result.

displaystring

Label for the column in notifications. Defaults to name.

aggregationstring

Aggregation applied to the column across all rows of the query result: SUM, COUNT, COUNT_DISTINCT, AVG, MEDIAN, MIN, MAX or STDDEV. If not set, the value in the first row is used, which is equivalent to using First row in the UI.

Values:

• SUM
• COUNT
• COUNT_DISTINCT
• AVG
• MEDIAN
• MIN
• MAX
• STDDEV

comparison_operatorstringRequired

Operator used for comparison in alert evaluation. The alert is triggered when the comparison of the source value with the threshold is true. IS_NULL and IS_NOT_NULL take no threshold.

Values:

• LESS_THAN
• GREATER_THAN
• EQUAL
• NOT_EQUAL
• GREATER_THAN_OR_EQUAL
• LESS_THAN_OR_EQUAL
• IS_NULL
• IS_NOT_NULL

thresholdobject

Threshold to compare the source column against, either another column or a fixed value. Not needed when comparison_operator is IS_NULL or IS_NOT_NULL.

Show child attributesHide child attributes

columnobject

Compare the source against another column of the query result.

Show child attributesHide child attributes

namestringRequired

Name of the column in the query result.

displaystring

Label for the column in notifications. Defaults to name.

aggregationstring

Aggregation applied to the column across all rows of the query result: SUM, COUNT, COUNT_DISTINCT, AVG, MEDIAN, MIN, MAX or STDDEV. If not set, the value in the first row is used, which is equivalent to using First row in the UI.

Values:

• SUM
• COUNT
• COUNT_DISTINCT
• AVG
• MEDIAN
• MIN
• MAX
• STDDEV

valueobject

Compare the source against a fixed value.

Show child attributesHide child attributes

string_valuestring

String threshold, for string or timestamp columns.

Example: foo

double_valuedouble

Numeric threshold, for numeric columns.

Example: 1.25

bool_valueboolean

Boolean threshold, for boolean columns.

Example: true

notificationobject

User or Notification Destination to notify when alert is triggered.

Show child attributesHide child attributes

subscriptionsarray of objectUnordered list

Users and notification destinations that receive notifications.

Show child attributesHide child attributes

user_emailstring

Email address of the workspace user to notify.

destination_idstring

ID of the notification destination to notify, as returned by the Notification Destinations API.

Example: 8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b

retrigger_secondsint32

Number of seconds an alert waits after being triggered before it is allowed to send another notification. If set to 0 or omitted, the alert will not send any further notifications after the first trigger Setting this value to 1 allows the alert to send a notification on every evaluation where the condition is met, effectively making it always retrigger for notification purposes.

Example: 0

notify_on_okboolean

Whether to notify alert subscribers when alert returns back to normal.

empty_result_statestring

Alert state if result is empty. If not set, an empty result sets the state to ERROR. Please avoid setting this field to be UNKNOWN because UNKNOWN state is planned to be deprecated.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

scheduleobjectRequired

Schedule on which the alert runs its query and evaluates the condition.

Show child attributesHide child attributes

quartz_cron_schedulestringRequired

A cron expression using quartz syntax that specifies the schedule for this alert. Should use the quartz format described here: http://www.quartz-scheduler.org/documentation/quartz-2.1.7/tutorials/tutorial-lesson-06.html

Example: 0 0 9 * * ?

timezone_idstringRequired

A Java timezone id. The schedule will be resolved using this timezone. This will be combined with the quartz_cron_schedule to determine the schedule. See https://docs.databricks.com/sql/language-manual/sql-ref-syntax-aux-conf-mgmt-set-timezone.html for details.

Example: America/Los_Angeles

pause_statusstring

Indicates whether this schedule is paused. While paused, the alert is not evaluated.

Default: UNPAUSED

Values:

• UNPAUSED
• PAUSED

custom_summarystring

Custom summary for the alert, used as the notification subject. Interpreted according to custom_template_format.

custom_descriptionstring

Custom description for the alert, used as the notification body. Interpreted according to custom_template_format. The available template variables are listed at https://docs.databricks.com/aws/en/sql/user/alerts/create#notification-templates.

run_asobject

Specifies the identity that will be used to run the alert. This field allows you to configure alerts to run as a specific user or service principal.

• For user identity: Set user_name to the email of an active workspace user. Users can only set this to their own email.
• For service principal: Set service_principal_name to the application ID. Requires the servicePrincipal/user role. If not specified, the alert will run as the request user.

Show child attributesHide child attributes

user_namestring

The email of an active workspace user. Can only set this field to their own email.

Example: user@databricks.com

service_principal_namestring

Application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: 692bc6d0-ffa3-11ed-be56-0242ac120002

parametersarray of objectBetaUnordered list

A list of parameters to pass into the alert SQL query statement containing parameter markers. Static values only.

Reference a parameter in the query text as :name. Each parameter must have a unique, non-empty name. Each parameter consists of a name, a value, and optionally a type. To represent a NULL value, the value field may be omitted or set to null explicitly. If the type field is omitted, the value is interpreted as a string.

If the type is given, parameters will be checked for type correctness according to the given type. A value is correct if the provided string can be converted to the requested type using the cast function. The exact semantics are described in the section cast function of the SQL language reference.

Show child attributesHide child attributes

namestringRequiredBeta

The name of the parameter. Reference it in the query text as :name. Required, must be non-empty, and must be unique across the alert's parameters.

Example: region

valuestringBeta

The value bound to the parameter, represented as a string. If omitted, the value is interpreted as NULL.

Example: US

typestringBeta

The SQL data type of the parameter, for example STRING, INT, or DECIMAL(10, 2). If no type is given the type is assumed to be STRING. Complex types such as ARRAY, MAP, and STRUCT are not supported.

Example: STRING

custom_template_formatstringPublic Preview

The format used to interpret the custom_summary and custom_description templates.

HTML treats both templates as HTML with Mustache {{VARIABLE_NAME}} placeholders. MARKDOWN treats them as Markdown with allowlisted @VARIABLE_NAME placeholders and converts them to the format each notification destination expects, so a single template renders correctly in email, Slack, and Microsoft Teams.

When unset, the API applies no default. Responses omit the field unless a format is stored, and a template with no format is rendered as HTML.

Values:

• HTML
• MARKDOWN

Response

Returns the Alert object.

View as Markdown

Request

Minimal alert notifying a userAlert with aggregation, notification destination, custom template and query parameter

{
  "display_name": "Daily revenue below target",
  "evaluation": {
    "comparison_operator": "LESS_THAN",
    "notification": {
      "subscriptions": [
        {
          "user_email": "user@example.com"
        }
      ]
    },
    "source": {
      "name": "revenue"
    },
    "threshold": {
      "value": {
        "double_value": 50000
      }
    }
  },
  "query_text": "SELECT sum(amount) AS revenue FROM main.sales.orders WHERE order_date = current_date() - 1",
  "schedule": {
    "quartz_cron_schedule": "0 0 9 * * ?",
    "timezone_id": "UTC"
  },
  "warehouse_id": "a7066a8ef796be84"
}

Response

Minimal alert notifying a userAlert with aggregation, notification destination, custom template and query parameter

{
  "create_time": "2025-03-15T09:00:00Z",
  "display_name": "Daily revenue below target",
  "effective_run_as": {
    "user_name": "user@example.com"
  },
  "evaluation": {
    "comparison_operator": "LESS_THAN",
    "notification": {
      "subscriptions": [
        {
          "user_email": "user@example.com"
        }
      ]
    },
    "source": {
      "name": "revenue"
    },
    "threshold": {
      "value": {
        "double_value": 50000
      }
    }
  },
  "id": "1927647905808834",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@example.com",
  "query_text": "SELECT sum(amount) AS revenue FROM main.sales.orders WHERE order_date = current_date() - 1",
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 9 * * ?",
    "timezone_id": "UTC"
  },
  "update_time": "2025-03-15T09:00:00Z",
  "warehouse_id": "a7066a8ef796be84"
}

Update an alert GA

PATCH /api/2.0/alerts/{id}

Updates an alert. Only the fields listed in update_mask are changed; all other fields keep their current values.

API scopes: alerts

Parameters

idstringRequiredIDImmutablepath

The canonical identifier of the alert to retrieve information about.

Example: 1927647905808833

update_maskstringRequiredquery

Comma-separated list of the alert fields to update, for example display_name,query_text or schedule.pause_status. Only the listed fields are changed; all other fields keep their current values. parent_path cannot be updated.

Request body

display_namestringRequired

The display name of the alert.

Example: Example alert

parent_pathstring

The workspace path of the folder containing the alert. Can only be set on create, and cannot be updated.

Example: /Users/user@acme.com

query_textstringRequired

Text of the query to be run.

Example: SELECT 1

warehouse_idstringRequired

ID of the SQL warehouse attached to the alert.

Example: a7066a8ef796be84

run_as_user_namestringDeprecated

Deprecated: Use run_as field instead. This field will be removed in a future release. The run as username or application ID of service principal. On Create and Update, this field can be set to application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: user@acme.com

evaluationobjectRequired

Condition evaluated against the query result, and who is notified when it is met.

Show child attributesHide child attributes

sourceobjectRequired

Source column from result to use to evaluate alert

Show child attributesHide child attributes

namestringRequired

Name of the column in the query result.

displaystring

Label for the column in notifications. Defaults to name.

aggregationstring

Aggregation applied to the column across all rows of the query result: SUM, COUNT, COUNT_DISTINCT, AVG, MEDIAN, MIN, MAX or STDDEV. If not set, the value in the first row is used, which is equivalent to using First row in the UI.

Values:

• SUM
• COUNT
• COUNT_DISTINCT
• AVG
• MEDIAN
• MIN
• MAX
• STDDEV

comparison_operatorstringRequired

Operator used for comparison in alert evaluation. The alert is triggered when the comparison of the source value with the threshold is true. IS_NULL and IS_NOT_NULL take no threshold.

Values:

• LESS_THAN
• GREATER_THAN
• EQUAL
• NOT_EQUAL
• GREATER_THAN_OR_EQUAL
• LESS_THAN_OR_EQUAL
• IS_NULL
• IS_NOT_NULL

thresholdobject

Threshold to compare the source column against, either another column or a fixed value. Not needed when comparison_operator is IS_NULL or IS_NOT_NULL.

Show child attributesHide child attributes

columnobject

Compare the source against another column of the query result.

Show child attributesHide child attributes

namestringRequired

Name of the column in the query result.

displaystring

Label for the column in notifications. Defaults to name.

aggregationstring

Aggregation applied to the column across all rows of the query result: SUM, COUNT, COUNT_DISTINCT, AVG, MEDIAN, MIN, MAX or STDDEV. If not set, the value in the first row is used, which is equivalent to using First row in the UI.

Values:

• SUM
• COUNT
• COUNT_DISTINCT
• AVG
• MEDIAN
• MIN
• MAX
• STDDEV

valueobject

Compare the source against a fixed value.

Show child attributesHide child attributes

string_valuestring

String threshold, for string or timestamp columns.

Example: foo

double_valuedouble

Numeric threshold, for numeric columns.

Example: 1.25

bool_valueboolean

Boolean threshold, for boolean columns.

Example: true

notificationobject

User or Notification Destination to notify when alert is triggered.

Show child attributesHide child attributes

subscriptionsarray of objectUnordered list

Users and notification destinations that receive notifications.

Show child attributesHide child attributes

user_emailstring

Email address of the workspace user to notify.

destination_idstring

ID of the notification destination to notify, as returned by the Notification Destinations API.

Example: 8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b

retrigger_secondsint32

Number of seconds an alert waits after being triggered before it is allowed to send another notification. If set to 0 or omitted, the alert will not send any further notifications after the first trigger Setting this value to 1 allows the alert to send a notification on every evaluation where the condition is met, effectively making it always retrigger for notification purposes.

Example: 0

notify_on_okboolean

Whether to notify alert subscribers when alert returns back to normal.

empty_result_statestring

Alert state if result is empty. If not set, an empty result sets the state to ERROR. Please avoid setting this field to be UNKNOWN because UNKNOWN state is planned to be deprecated.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

scheduleobjectRequired

Schedule on which the alert runs its query and evaluates the condition.

Show child attributesHide child attributes

quartz_cron_schedulestringRequired

A cron expression using quartz syntax that specifies the schedule for this alert. Should use the quartz format described here: http://www.quartz-scheduler.org/documentation/quartz-2.1.7/tutorials/tutorial-lesson-06.html

Example: 0 0 9 * * ?

timezone_idstringRequired

A Java timezone id. The schedule will be resolved using this timezone. This will be combined with the quartz_cron_schedule to determine the schedule. See https://docs.databricks.com/sql/language-manual/sql-ref-syntax-aux-conf-mgmt-set-timezone.html for details.

Example: America/Los_Angeles

pause_statusstring

Indicates whether this schedule is paused. While paused, the alert is not evaluated.

Default: UNPAUSED

Values:

• UNPAUSED
• PAUSED

custom_summarystring

Custom summary for the alert, used as the notification subject. Interpreted according to custom_template_format.

custom_descriptionstring

Custom description for the alert, used as the notification body. Interpreted according to custom_template_format. The available template variables are listed at https://docs.databricks.com/aws/en/sql/user/alerts/create#notification-templates.

run_asobject

Specifies the identity that will be used to run the alert. This field allows you to configure alerts to run as a specific user or service principal.

• For user identity: Set user_name to the email of an active workspace user. Users can only set this to their own email.
• For service principal: Set service_principal_name to the application ID. Requires the servicePrincipal/user role. If not specified, the alert will run as the request user.

Show child attributesHide child attributes

user_namestring

The email of an active workspace user. Can only set this field to their own email.

Example: user@databricks.com

service_principal_namestring

Application ID of an active service principal. Setting this field requires the servicePrincipal/user role.

Example: 692bc6d0-ffa3-11ed-be56-0242ac120002

parametersarray of objectBetaUnordered list

A list of parameters to pass into the alert SQL query statement containing parameter markers. Static values only.

Reference a parameter in the query text as :name. Each parameter must have a unique, non-empty name. Each parameter consists of a name, a value, and optionally a type. To represent a NULL value, the value field may be omitted or set to null explicitly. If the type field is omitted, the value is interpreted as a string.

If the type is given, parameters will be checked for type correctness according to the given type. A value is correct if the provided string can be converted to the requested type using the cast function. The exact semantics are described in the section cast function of the SQL language reference.

Show child attributesHide child attributes

namestringRequiredBeta

The name of the parameter. Reference it in the query text as :name. Required, must be non-empty, and must be unique across the alert's parameters.

Example: region

valuestringBeta

The value bound to the parameter, represented as a string. If omitted, the value is interpreted as NULL.

Example: US

typestringBeta

The SQL data type of the parameter, for example STRING, INT, or DECIMAL(10, 2). If no type is given the type is assumed to be STRING. Complex types such as ARRAY, MAP, and STRUCT are not supported.

Example: STRING

custom_template_formatstringPublic Preview

The format used to interpret the custom_summary and custom_description templates.

HTML treats both templates as HTML with Mustache {{VARIABLE_NAME}} placeholders. MARKDOWN treats them as Markdown with allowlisted @VARIABLE_NAME placeholders and converts them to the format each notification destination expects, so a single template renders correctly in email, Slack, and Microsoft Teams.

When unset, the API applies no default. Responses omit the field unless a format is stored, and a template with no format is rendered as HTML.

Values:

• HTML
• MARKDOWN

Response

Returns the Alert object.

View as Markdown

Request

Rename the alert and pause its schedule, with update_mask=display_name,schedule.pause_status

{
  "display_name": "Failed orders above threshold (paused)",
  "schedule": {
    "pause_status": "PAUSED"
  }
}

Response

{
  "create_time": "2025-03-15T10:00:00Z",
  "custom_description": "<p>{{ALERT_COLUMN}} is {{QUERY_RESULT_VALUE}}, above the threshold of {{ALERT_THRESHOLD}}.</p>",
  "custom_summary": "{{ALERT_NAME}} is {{ALERT_STATUS}}",
  "custom_template_format": "HTML",
  "display_name": "Failed orders above threshold (paused)",
  "effective_run_as": {
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "OK",
    "last_evaluated_at": "2025-03-16T09:00:12Z",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 3600,
      "subscriptions": [
        {
          "user_email": "user@example.com"
        },
        {
          "destination_id": "8f3a2b1c-4d5e-4f60-9a7b-1c2d3e4f5a6b"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "Failed orders",
      "name": "failed_orders"
    },
    "state": "TRIGGERED",
    "threshold": {
      "value": {
        "double_value": 100
      }
    }
  },
  "id": "1927647905808833",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@example.com",
  "parameters": [
    {
      "name": "region",
      "type": "STRING",
      "value": "US"
    }
  ],
  "parent_path": "/Users/user@example.com",
  "query_text": "SELECT region, failed_orders FROM main.sales.order_health WHERE region = :region",
  "run_as": {
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "schedule": {
    "pause_status": "PAUSED",
    "quartz_cron_schedule": "0 0 * * * ?",
    "timezone_id": "America/Los_Angeles"
  },
  "update_time": "2025-03-20T16:30:00Z",
  "warehouse_id": "a7066a8ef796be84"
}

Delete an alert (legacy TrashAlert) GA

DELETE /api/2.0/alerts/{id}

Moves an alert to the trash. Trashed alerts immediately disappear from list views, and can no longer trigger. You can restore a trashed alert through the UI. A trashed alert is permanently deleted after 30 days.

API scopes: alerts

Parameters

idstringRequiredpath

ID of the alert to move to the trash.

Example: 1927647905808833

View as Markdown

Response

{}