Alert

View as Markdown

GetGET /api/2.0/sql/alerts/{id}CreatePOST /api/2.0/sql/alertsUpdatePATCH /api/2.0/sql/alerts/{id}DeleteDELETE /api/2.0/sql/alerts/{id}

Alert object

idstring

UUID identifying the alert.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

The display name of the alert.

Example: Example alert

query_idstring

UUID of the query attached to the alert.

Example: dee5cca8-1c79-4b5e-a711-e7f9d241bdf6

statestring

Current state of the alert's trigger status. This field is set to UNKNOWN if the alert has not yet been evaluated or ran into an error during the last evaluation.

Values: UNKNOWN, OK, TRIGGERED

Example: UNKNOWN

seconds_to_retriggerint32

Number of seconds an alert must wait after being triggered to rearm itself. After rearming, it can be triggered again. If 0 or not specified, the alert will not be triggered again.

Example: 0

lifecycle_statestring

The workspace state of the alert. Used for tracking trashed status.

Values: ACTIVE, TRASHED

Example: ACTIVE

trigger_timestring

Timestamp when the alert was last triggered, if the alert has been triggered before.

custom_bodystring

Custom body of alert notification, if it exists. See here for custom templating instructions.

Example: custom body

custom_subjectstring

Custom subject of alert notification, if it exists. This can include email subject entries and Slack notification headers, for example. See here for custom templating instructions.

Example: custom subject

conditionobject

Trigger conditions of the alert.

Show child attributesHide child attributes

opstring

Operator used for comparison in alert evaluation.

Values: GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, EQUAL, NOT_EQUAL, IS_NULL

operandobject

Name of the column from the query result to use for comparison in alert evaluation.

Show child attributesHide child attributes

valueobject

Show child attributesHide child attributes

string_valuestring

Example: foo

double_valuedouble

Example: 1.25

bool_valueboolean

Example: true

columnobject

Show child attributesHide child attributes

namestring

Example: col

thresholdobject

Threshold value used for comparison in alert evaluation.

Show child attributesHide child attributes

valueobject

Show child attributesHide child attributes

string_valuestring

Example: foo

double_valuedouble

Example: 1.25

bool_valueboolean

Example: true

columnobject

Show child attributesHide child attributes

namestring

Example: col

empty_result_statestring

Alert state if result is empty.

Values: UNKNOWN, OK, TRIGGERED

owner_user_namestring

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

Example: user@acme.com

parent_pathstring

The workspace path of the folder containing the alert.

Example: /Users/user@acme.com

create_timestring

The timestamp indicating when the alert was created.

update_timestring

The timestamp indicating when the alert was updated.

notify_on_okboolean

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

View as Markdown

The Alert object

{
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "display_name": "Example alert",
  "query_id": "dee5cca8-1c79-4b5e-a711-e7f9d241bdf6",
  "state": "UNKNOWN",
  "seconds_to_retrigger": 0,
  "lifecycle_state": "ACTIVE",
  "trigger_time": "string",
  "custom_body": "custom body",
  "custom_subject": "custom subject",
  "condition": {
    "op": "string",
    "operand": {},
    "threshold": {},
    "empty_result_state": "string"
  },
  "owner_user_name": "user@acme.com",
  "parent_path": "/Users/user@acme.com",
  "create_time": "string",
  "update_time": "string",
  "notify_on_ok": true
}

Get GA

GET /api/2.0/sql/alerts/{id}

Gets an alert.

API scopes: sql

Parameters

idstringpath

Response

Returns the Alert object.

View as Markdown

Response

{
  "condition": {
    "op": "GREATER_THAN",
    "operand": {
      "column": {
        "name": "foo"
      }
    },
    "threshold": {
      "value": {
        "string_value": "test"
      }
    }
  },
  "create_time": "2019-08-24T14:15:22Z",
  "display_name": "Test alert",
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user.name@acme.com",
  "parent_path": "/Workspace/Users/user.name@acme.com",
  "query_id": "dee5cca8-1c79-4b5e-a711-e7f9d241bdf6",
  "seconds_to_retrigger": 0,
  "state": "OK",
  "update_time": "2019-08-24T14:15:22Z"
}

Create GA

POST /api/2.0/sql/alerts

Creates an alert.

API scopes: sql

Request body

alertobject

Show child attributesHide child attributes

idstring

UUID identifying the alert.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

The display name of the alert.

Example: Example alert

query_idstring

UUID of the query attached to the alert.

Example: dee5cca8-1c79-4b5e-a711-e7f9d241bdf6

statestring

Current state of the alert's trigger status. This field is set to UNKNOWN if the alert has not yet been evaluated or ran into an error during the last evaluation.

Values: UNKNOWN, OK, TRIGGERED

Example: UNKNOWN

seconds_to_retriggerint32

Number of seconds an alert must wait after being triggered to rearm itself. After rearming, it can be triggered again. If 0 or not specified, the alert will not be triggered again.

Example: 0

lifecycle_statestring

The workspace state of the alert. Used for tracking trashed status.

Values: ACTIVE, TRASHED

Example: ACTIVE

trigger_timestring

Timestamp when the alert was last triggered, if the alert has been triggered before.

custom_bodystring

Custom body of alert notification, if it exists. See here for custom templating instructions.

Example: custom body

custom_subjectstring

Custom subject of alert notification, if it exists. This can include email subject entries and Slack notification headers, for example. See here for custom templating instructions.

Example: custom subject

conditionobject

Trigger conditions of the alert.

Show child attributesHide child attributes

opstring

Operator used for comparison in alert evaluation.

Values: GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, EQUAL, NOT_EQUAL, IS_NULL

operandobject

Name of the column from the query result to use for comparison in alert evaluation.

Show child attributesHide child attributes

valueobjectRequired

columnobjectRequired

thresholdobject

Threshold value used for comparison in alert evaluation.

Show child attributesHide child attributes

valueobjectRequired

columnobjectRequired

empty_result_statestring

Alert state if result is empty.

Values: UNKNOWN, OK, TRIGGERED

owner_user_namestring

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

Example: user@acme.com

parent_pathstring

The workspace path of the folder containing the alert.

Example: /Users/user@acme.com

create_timestring

The timestamp indicating when the alert was created.

update_timestring

The timestamp indicating when the alert was updated.

notify_on_okboolean

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

auto_resolve_display_nameboolean

If true, automatically resolve alert display name conflicts. Otherwise, fail the request if the alert's display name conflicts with an existing alert's display name.

Default: true

Response

Returns the Alert object.

View as Markdown

Request

{
  "alert": {
    "condition": {
      "op": "GREATER_THAN",
      "operand": {
        "column": {
          "name": "foo"
        }
      },
      "threshold": {
        "value": {
          "double_value": 1
        }
      }
    },
    "display_name": "Test alert",
    "parent_path": "/Workspace/Users/user.name@acme.com",
    "query_id": "dee5cca8-1c79-4b5e-a71m1-e7f9d241bdf6",
    "seconds_to_retrigger": 0
  }
}

Response

{
  "condition": {
    "op": "GREATER_THAN",
    "operand": {
      "column": {
        "name": "foo"
      }
    },
    "threshold": {
      "value": {
        "double_value": 1
      }
    }
  },
  "create_time": "2019-08-24T14:15:22Z",
  "display_name": "Test alert",
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user.name@acme.com",
  "parent_path": "/Workspace/Users/user.name@acme.com",
  "query_id": "dee5cca8-1c79-4b5e-a711-e7f9d241bdf6",
  "seconds_to_retrigger": 0,
  "state": "OK",
  "update_time": "2019-08-24T14:15:22Z"
}

Update GA

PATCH /api/2.0/sql/alerts/{id}

Updates an alert.

API scopes: sql

Parameters

idstringpath

Request body

alertobject

Show child attributesHide child attributes

idstring

UUID identifying the alert.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

The display name of the alert.

Example: Example alert

query_idstring

UUID of the query attached to the alert.

Example: dee5cca8-1c79-4b5e-a711-e7f9d241bdf6

statestring

Current state of the alert's trigger status. This field is set to UNKNOWN if the alert has not yet been evaluated or ran into an error during the last evaluation.

Values: UNKNOWN, OK, TRIGGERED

Example: UNKNOWN

seconds_to_retriggerint32

Number of seconds an alert must wait after being triggered to rearm itself. After rearming, it can be triggered again. If 0 or not specified, the alert will not be triggered again.

Example: 0

lifecycle_statestring

The workspace state of the alert. Used for tracking trashed status.

Values: ACTIVE, TRASHED

Example: ACTIVE

trigger_timestring

Timestamp when the alert was last triggered, if the alert has been triggered before.

custom_bodystring

Custom body of alert notification, if it exists. See here for custom templating instructions.

Example: custom body

custom_subjectstring

Custom subject of alert notification, if it exists. This can include email subject entries and Slack notification headers, for example. See here for custom templating instructions.

Example: custom subject

conditionobject

Trigger conditions of the alert.

Show child attributesHide child attributes

opstring

Operator used for comparison in alert evaluation.

Values: GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, EQUAL, NOT_EQUAL, IS_NULL

operandobject

Name of the column from the query result to use for comparison in alert evaluation.

Show child attributesHide child attributes

valueobjectRequired

columnobjectRequired

thresholdobject

Threshold value used for comparison in alert evaluation.

Show child attributesHide child attributes

valueobjectRequired

columnobjectRequired

empty_result_statestring

Alert state if result is empty.

Values: UNKNOWN, OK, TRIGGERED

owner_user_namestring

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

Example: user@acme.com

parent_pathstring

The workspace path of the folder containing the alert.

Example: /Users/user@acme.com

create_timestring

The timestamp indicating when the alert was created.

update_timestring

The timestamp indicating when the alert was updated.

notify_on_okboolean

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

update_maskstring

auto_resolve_display_nameboolean

If true, automatically resolve alert display name conflicts. Otherwise, fail the request if the alert's display name conflicts with an existing alert's display name.

Default: true

Response

Returns the Alert object.

View as Markdown

Request

{
  "alert": {
    "condition": {
      "op": "EQUAL",
      "operand": {
        "column": {
          "name": "bar"
        }
      },
      "threshold": {
        "value": {
          "bool_value": true
        }
      }
    },
    "display_name": "Renamed alert"
  },
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "update_mask": "display_name,condition"
}

Response

{
  "condition": {
    "op": "EQUAL",
    "operand": {
      "column": {
        "name": "bar"
      }
    },
    "threshold": {
      "value": {
        "bool_value": true
      }
    }
  },
  "create_time": "2019-08-24T14:15:22Z",
  "display_name": "Renamed alert",
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user.name@acme.com",
  "parent_path": "/Workspace/Users/user.name@acme.com",
  "query_id": "dee5cca8-1c79-4b5e-a711-e7f9d241bdf6",
  "seconds_to_retrigger": 0,
  "state": "OK",
  "update_time": "2019-08-24T14:15:22Z"
}

Delete GA

DELETE /api/2.0/sql/alerts/{id}

Moves an alert to the trash. Trashed alerts immediately disappear from searches and 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: sql

Parameters

idstringpath

View as Markdown

Response

{}