Alert

View as Markdown

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

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

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. Deprecated: Use run_as field instead. This field will be removed in a future release.

Example: user@acme.com

evaluationobject

Show child attributesHide child attributes

sourceobject

Source column from result to use to evaluate alert

Show child attributesHide child attributes

namestring

displaystring

aggregationstring

If not set, the behavior 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.

Values:

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

thresholdobject

Threshold to user for alert evaluation, can be a column or a value.

Show child attributesHide child attributes

columnobject

Show child attributesHide child attributes

namestring

displaystring

aggregationstring

If not set, the behavior is equivalent to using First row in the UI.

Values:

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

valueobject

Show child attributesHide child attributes

string_valuestring

Example: foo

double_valuedouble

Example: 1.25

bool_valueboolean

Example: true

notificationobject

User or Notification Destination to notify when alert is triggered.

Show child attributesHide child attributes

subscriptionsarray of objectUnordered list

Show child attributesHide child attributes

user_emailstring

destination_idstring

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.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

last_evaluated_atstringOutput only

Timestamp of the last evaluation.

empty_result_statestring

Alert state if result is empty. Please avoid setting this field to be UNKNOWN because UNKNOWN state is planned to be deprecated.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

scheduleobject

Show child attributesHide child attributes

quartz_cron_schedulestring

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

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.

pause_statusstring

Indicate whether this schedule is paused or not.

Default: UNPAUSED

Values:

• UNPAUSED
• PAUSED

lifecycle_statestringOutput only

Indicates whether the query is trashed.

Values:

• ACTIVE
• DELETED

custom_summarystring

Custom summary for the alert. Interpreted according to custom_template_format.

custom_descriptionstring

Custom description for the alert. Interpreted according to custom_template_format.

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_formatstringBeta

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

{
  "id": "1927647905808833",
  "display_name": "Example alert",
  "owner_user_name": "user@acme.com",
  "create_time": "string",
  "update_time": "string",
  "parent_path": "/Users/user@acme.com",
  "query_text": "SELECT 1",
  "warehouse_id": "a7066a8ef796be84",
  "run_as_user_name": "user@acme.com",
  "evaluation": {
    "source": {},
    "comparison_operator": "LESS_THAN",
    "threshold": {},
    "notification": {},
    "state": "UNKNOWN",
    "last_evaluated_at": "string",
    "empty_result_state": "UNKNOWN"
  },
  "schedule": {
    "quartz_cron_schedule": "string",
    "timezone_id": "string",
    "pause_status": "UNPAUSED"
  },
  "lifecycle_state": "ACTIVE",
  "custom_summary": "string",
  "custom_description": "string",
  "run_as": {
    "user_name": "user@databricks.com",
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "effective_run_as": {
    "user_name": "user@databricks.com",
    "service_principal_name": "692bc6d0-ffa3-11ed-be56-0242ac120002"
  },
  "parameters": [
    {
      "name": "region",
      "value": "US",
      "type": "STRING"
    }
  ],
  "custom_template_format": "HTML"
}

Get an alert GA

GET /api/2.0/alerts/{id}

Gets an alert.

API scopes: alerts

Parameters

idstringRequiredpath

Response

Returns the Alert object.

View as Markdown

Response

{
  "create_time": "2019-08-24T14:15:22Z",
  "custom_description": "Custom email body",
  "custom_summary": "Custom email subject",
  "display_name": "Example alert",
  "evaluation": {
    "comparison_operator": "LESS_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "state": "UNKNOWN",
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "id": "1927647905808833",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parent_path": "/Users/user@acme.com",
  "query_text": "SELECT 1 as x",
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 10 * * ?",
    "timezone_id": "UTC"
  },
  "update_time": "2019-08-24T14:15:22Z",
  "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_sizeint32<= 100query

Default: 20

Response

Returns a list of Alert objects.

View as Markdown

Response

{
  "next_page_token": "eDg",
  "results": [
    {
      "create_time": "2019-08-24T14:15:22Z",
      "custom_description": "Custom email body",
      "custom_summary": "Custom email subject",
      "display_name": "Example alert",
      "evaluation": {
        "comparison_operator": "LESS_THAN",
        "empty_result_state": "UNKNOWN",
        "notification": {
          "notify_on_ok": true,
          "retrigger_seconds": 0,
          "subscriptions": [
            {
              "user_email": "user@acme.com"
            }
          ]
        },
        "source": {
          "aggregation": "SUM",
          "display": "x",
          "name": "x"
        },
        "state": "UNKNOWN",
        "threshold": {
          "value": {
            "double_value": 1.25
          }
        }
      },
      "id": "1927647905808833",
      "lifecycle_state": "ACTIVE",
      "owner_user_name": "user@acme.com",
      "parent_path": "/Users/user@acme.com",
      "query_text": "SELECT 1 as x",
      "schedule": {
        "pause_status": "UNPAUSED",
        "quartz_cron_schedule": "0 0 10 * * ?",
        "timezone_id": "UTC"
      },
      "update_time": "2019-08-24T14:15:22Z",
      "warehouse_id": "a7066a8ef796be84"
    },
    {
      "create_time": "2019-08-24T14:15:22Z",
      "display_name": "Another alert",
      "evaluation": {
        "comparison_operator": "LESS_THAN",
        "empty_result_state": "UNKNOWN",
        "notification": {
          "notify_on_ok": true,
          "retrigger_seconds": 0,
          "subscriptions": [
            {
              "user_email": "user@acme.com"
            }
          ]
        },
        "source": {
          "display": "x",
          "name": "x"
        },
        "state": "UNKNOWN",
        "threshold": {
          "value": {
            "double_value": 1.25
          }
        }
      },
      "id": "1927647905808834",
      "lifecycle_state": "ACTIVE",
      "owner_user_name": "user@acme.com",
      "parent_path": "/Users/user@acme.com",
      "query_text": "SELECT rand() as x",
      "schedule": {
        "pause_status": "UNPAUSED",
        "quartz_cron_schedule": "0 0 10 * * ?",
        "timezone_id": "UTC"
      },
      "update_time": "2019-08-24T14:15:22Z",
      "warehouse_id": "a7066a8ef796be84"
    }
  ]
}

Create an alert GA

POST /api/2.0/alerts

Create Alert

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

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. Deprecated: Use run_as field instead. This field will be removed in a future release.

Example: user@acme.com

evaluationobjectRequired

Show child attributesHide child attributes

sourceobjectRequired

Source column from result to use to evaluate alert

Show child attributesHide child attributes

namestringRequired

displaystring

aggregationstring

If not set, the behavior 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.

Values:

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

thresholdobject

Threshold to user for alert evaluation, can be a column or a value.

Show child attributesHide child attributes

columnobject

Show child attributesHide child attributes

namestringRequired

displaystring

aggregationstring

If not set, the behavior is equivalent to using First row in the UI.

Values:

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

valueobject

Show child attributesHide child attributes

string_valuestring

Example: foo

double_valuedouble

Example: 1.25

bool_valueboolean

Example: true

notificationobject

User or Notification Destination to notify when alert is triggered.

Show child attributesHide child attributes

subscriptionsarray of objectUnordered list

Show child attributesHide child attributes

user_emailstring

destination_idstring

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. Please avoid setting this field to be UNKNOWN because UNKNOWN state is planned to be deprecated.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

scheduleobjectRequired

Show child attributesHide child attributes

quartz_cron_schedulestringRequired

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

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.

pause_statusstring

Indicate whether this schedule is paused or not.

Default: UNPAUSED

Values:

• UNPAUSED
• PAUSED

custom_summarystring

Custom summary for the alert. Interpreted according to custom_template_format.

custom_descriptionstring

Custom description for the alert. Interpreted according to custom_template_format.

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_formatstringBeta

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

{
  "custom_description": "Custom email body",
  "custom_summary": "Custom email subject",
  "display_name": "Example alert",
  "evaluation": {
    "comparison_operator": "LESS_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "parent_path": "/Users/user@acme.com",
  "query_text": "SELECT 1 as x",
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 10 * * ?",
    "timezone_id": "UTC"
  },
  "warehouse_id": "a7066a8ef796be84"
}

Response

{
  "create_time": "2019-08-24T14:15:22Z",
  "custom_description": "Custom email body",
  "custom_summary": "Custom email subject",
  "display_name": "Example alert",
  "evaluation": {
    "comparison_operator": "LESS_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "state": "UNKNOWN",
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "id": "1927647905808833",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parent_path": "/Users/user@acme.com",
  "query_text": "SELECT 1 as x",
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 10 * * ?",
    "timezone_id": "UTC"
  },
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "a7066a8ef796be84"
}

Update an alert GA

PATCH /api/2.0/alerts/{id}

Update alert

API scopes: alerts

Parameters

idstringRequiredIDImmutablepath

The canonical identifier of the alert to retrieve information about.

Example: 1927647905808833

update_maskstringRequiredquery

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

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. Deprecated: Use run_as field instead. This field will be removed in a future release.

Example: user@acme.com

evaluationobjectRequired

Show child attributesHide child attributes

sourceobjectRequired

Source column from result to use to evaluate alert

Show child attributesHide child attributes

namestringRequired

displaystring

aggregationstring

If not set, the behavior 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.

Values:

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

thresholdobject

Threshold to user for alert evaluation, can be a column or a value.

Show child attributesHide child attributes

columnobject

Show child attributesHide child attributes

namestringRequired

displaystring

aggregationstring

If not set, the behavior is equivalent to using First row in the UI.

Values:

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

valueobject

Show child attributesHide child attributes

string_valuestring

Example: foo

double_valuedouble

Example: 1.25

bool_valueboolean

Example: true

notificationobject

User or Notification Destination to notify when alert is triggered.

Show child attributesHide child attributes

subscriptionsarray of objectUnordered list

Show child attributesHide child attributes

user_emailstring

destination_idstring

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. Please avoid setting this field to be UNKNOWN because UNKNOWN state is planned to be deprecated.

Values:

• UNKNOWN
• TRIGGERED
• OK
• ERROR

scheduleobjectRequired

Show child attributesHide child attributes

quartz_cron_schedulestringRequired

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

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.

pause_statusstring

Indicate whether this schedule is paused or not.

Default: UNPAUSED

Values:

• UNPAUSED
• PAUSED

custom_summarystring

Custom summary for the alert. Interpreted according to custom_template_format.

custom_descriptionstring

Custom description for the alert. Interpreted according to custom_template_format.

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_formatstringBeta

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

{
  "display_name": "Renamed alert",
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "query_text": "SELECT 2 as x"
}

Response

{
  "create_time": "2019-08-24T14:15:22Z",
  "custom_description": "Custom email body",
  "custom_summary": "Custom email subject",
  "display_name": "Renamed alert",
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "id": "1927647905808833",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parent_path": "/Users/user@acme.com",
  "query_text": "SELECT 2 as x",
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 10 * * ?",
    "timezone_id": "UTC"
  },
  "update_time": "2019-08-24T14:15:22Z",
  "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

View as Markdown

Response

{}