Alert

An Alert is a object representation of complex logic to be executed by it's parent object Schedule. Alerts enable users to add logical expressions in conjunction with several backend alerting services to run after a given scheduled task. An Alert is comprised of 2 major components:

Component	Description
expressions	a list of expression objects containing the various parts of a logical expression.
actions	a list of action objects containing the necessary data to execute the action type.

Alerts will accept over 30 different data_types to include all Lighthouse and Yellow lab metrics. For a complete list and description of each available data_type please see Data Types

Tips

Alerts are intended for single Schedule use. i.e. one Alert services one Schedule.

Alert object

{
   "id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",     // uuid specific to Alert
   "expressions":[                                  // an array of expression objects denoting a logical expression
      {
         "joiner":"",                   // should be one of:  "", "and", "or" (first expression joiner is always "")
         "data_type":"test_score",      // the type of data being evaluated (one of: "test_score", "current_average", "seo_delta", "best_practices_delta", "performance_delta", "images_score", "logs", "health")
         "operator":"<=",               // operator used to evaluate expression. One of:  ">=", "<=" 
         "value":"80"                   // the value that "data_type" is being compared to
      },
      {
         "joiner":"or",
         "data_type":"current_average",
         "operator":"<=",
         "value":"75"
      }
   ],
   "actions":[                      // an array of action objects denoting what automated actions to complete when the expressions are evaluated
      {
         "action_type":"slack",     // one of: "slack", "phone", "email"
         "email":"",                // if using email: the email address to send an alert
         "phone":""                 // if using phone: the number to send a text to e.g +13335558888
      },
   ],
   "user":"example@gmail.com",                          // user denoted by email
   "schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",   // uuid specific to associated Schedule  
   "time_created":"2021-11-22T20:48:36.153402Z",        // timestamp of Alert creation
   "name":"My Scan Alert"                          // non-unique/non-binding string to help the user remember the alert
}
      

Create or Update Alert

There are two use cases for this endpoint, Creating and Updating Alerts.

POST - /alert

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{CURSION_API_BASE_URL}/alert'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}
data = {
    actions: [
        {
            action_type: "slack", 
            email: "", 
            phone: ""
        },
    ]
    alert_id: ""  # Insert <alert:id> if updating alert
    expressions: [
        {
            joiner: "", 
            data_type: "test_score", 
            operator: "<=", 
            value: "80"
        },
        {
            joiner: "or", 
            data_type: "current_average", 
            operator: "<=", 
            value: "75"
        }
    ]
    

    name: "My Scan Alert"
    schedule_id: "5dd6cc87-5f90-471f-84bd-a1b4c759ea33"
    site_id: "46053956-761b-4ca6-8cec-3be796695d12"
}

# send the request
res = requests.post(
    url=url,
    headers=headers,
    data=json.dumps(data)
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
   "expressions":[
      {
         "joiner":"",
         "data_type":"test_score",
         "operator":"<=",
         "value":"80"
      },
      {
         "joiner":"or",
         "data_type":"current_average",
         "operator":"<=",
         "value":"75"
      }
   ],
   "actions":[
      {
         "action_type":"slack",
         "email":"",
         "phone":""
      },
   ],
   "user":"example@gmail.com",
   "schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
   "time_created":"2021-11-22T20:48:36.153402Z",
   "name":"My Scan Alert"
}

Retrieve an Alert

This endpoint returns a single Alert object and is useful as a simple "detailed view" of the alert.

GET - /alert/<alert:id>

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/alert/<alert:id>'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.get(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
   "expressions":[
      {
         "joiner":"",
         "data_type":"test_score",
         "operator":"<=",
         "value":"80"
      },
      {
         "joiner":"or",
         "data_type":"current_average",
         "operator":"<=",
         "value":"75"
      }
   ],
   "actions":[
      {
         "action_type":"slack",
         "email":"",
         "phone":""
      },
   ],
   "user":"example@gmail.com",
   "schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
   "time_created":"2021-11-22T20:48:36.153402Z",
   "name":"My Scan Alert"
}

Retrieve many Alerts

This endpoint returns a paginated response with all Alert objects filtered by your account and ordered by time_created. This endpoint is useful when needing to displaying your sites in a table view for example. The limit parameter specifies the total number of objects you want returned per "group" (we recommend keeping this under 10 for best performance). The offset parameter specfies which "group" to return. For example, limit=10&offset=10 in a total dataset of 30 objects would return 10 alerts in range alert #10 - alert #20.

GET - /alert?limit=10&offset=0

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/alert?limit=10&offset=0'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.get(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "count":30,
   "next":"https://api.cursion.dev/v1/ops/alert?limit=10&offset=20",
   "previous":"https://api.cursion.dev/v1/ops/alert?limit=10&offset=10",
   "results":[
        {
            "id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
            "expressions":[
                {
                    "joiner":"",
                    "data_type":"test_score",
                    "operator":"<=",
                    "value":"80"
                },
                {
                    "joiner":"or",
                    "data_type":"current_average",
                    "operator":"<=",
                    "value":"75"
                }
            ],
            "actions":[
                {
                    "action_type":"slack",
                    "email":"",
                    "phone":""
                },
            ],
            "user":"example@gmail.com",
            "schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
            "time_created":"2021-11-22T20:48:36.153402Z",
            "name":"My Scan Alert"
        },
        {
            "id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
            "expressions":[
                {
                    "joiner":"",
                    "data_type":"test_score",
                    "operator":"<=",
                    "value":"80"
                },
                {
                    "joiner":"or",
                    "data_type":"current_average",
                    "operator":"<=",
                    "value":"75"
                }
            ],
            "actions":[
                {
                    "action_type":"phone",
                    "email":"",
                    "phone":"+13335558888"
                },
            ],
            "user":"example@gmail.com",
            "schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
            "time_created":"2021-11-22T20:48:36.153402Z",
            "name":"My Other Scan Alert"
        }

      ### SHORTENED FOR DISPLAY PURPOSES ###
   ]
}

Delete an Alert

Caution

Please use caution with this endpoint as it is irreversible.

DELETE - /alert/<alert:id>

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/alert/<alert:id>'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.delete(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
    "message": "Alert has been deleted"
}

Data Types

Below is a verbose list of all available data type names, a description of the data, and which task_types can utilize them.

---

Name (string)	Description	Task
health	Calculated health score from that Scan	Scan
logs	Total number of error logs found in that Scan	Scan
lighthouse_average	Average of all Lighthouse scores for that Scan	Scan
seo	SEO score for that Scan	Scan
performance	Perfomance score for that Scan	Scan
best_practices	Best Practices score for that Scan	Scan
accessibility	Accessibility score for that Scan	Scan
pwa	PWA score for that Scan	Scan
crux	CRUX score for that Scan	Scan
yellowlab_average	Average of all Yellow Lab scores for that Scan	Scan
pageWeight	Page Weight score for that Scan	Scan
images	Requests score for that Scan	Scan
domComplexity	DOM Complexity score for that Scan	Scan
javascriptComplexity	JS Complexity score for that Scan	Scan
badJavascript	Bad JS score for that Scan	Scan
jQuery	jQuery score for that Scan	Scan
cssComplexity	CSS Complexity score for that Scan	Scan
badCSS	Bad CSS score for that Scan	Scan
fonts	Fonts score for that Scan	Scan
serverConfig	Server Config score for that Scan	Scan
test_score	Calculated test score from that Test	Test
current_health	Calculated health score from second Scan	Test
current_lighthouse_average	Average of all Lighthouse scores from second Scan	Test
seo_delta	Difference in SEO scores	Test
performance_delta	Difference in Perfomance scores	Test
best_practice_deltas	Difference in Best Practices score	Test
accessibility_delta	Difference in Accessibility score	Test
pwa_delta	Difference in PWA scores	Test
crux_delta	Difference in CRUX scores	Test
current_yellowlab_average	Difference in Average of all Yellow Lab scores from second Scan	Test
pageWeight_delta	Difference in Page Weight score	Test
images_delta	Difference in Requests score	Test
domComplexity_delta	Difference in DOM Complexity score	Test
javascriptComplexity_delta	Difference in JS Complexity score	Test
badJavascript_delta	Difference in Bad JS score	Test
jQuery_delta	Difference in jQuery score	Test
cssComplexity_delta	Difference in CSS Complexity score	Test
badCSS_delta	Difference in Bad CSS score	Test
fonts_delta	Difference in Fonts score	Test
serverConfig_delta	Difference in Server Config score	Test
avg_image_score	The average score of all images compared in that Test	Test
image_scores	An array of image scores found in that Test	Test