Alerts API v2

Configure which alert notifications you'll receive about your Akamai network.

Learn more:

Overview

The Alerts API allows you to configure notifications about significant changes to your traffic based on continual tracking by Akamai’s network monitoring platform. It allows you to create and modify alerts based on a wide range of criteria, both static and dynamic, and to configure reports on anomalies. This API provides you with a programmatic interface to the same functionality available in Akamai Control Center.

NOTE: The most recent version 2 of the Alerts API detailed here provides full read-write access to alerts, along with additional reporting capabilities. The previous API version 1 it replaces provides a narrower set of read-only capabilities, accessing objects you can create only in Control Center.

See the Resources section for details on each API operation and the overall developer workflow. See Data for information on the data objects the API exchanges. See Errors for details on response codes.

Who should use this API

Use this API if you want to create your own automated mechanism to manage your alerts outside of Control Center. You can monitor any of the following:

  • High or low overall traffic (static or adaptive), incomplete downloads, and percentage of edge error responses.

  • Problems with streaming usage, bandwidth, errors, and number of concurrent streams.

  • Origin infrastructure failures due to connection problems, DNS mapping errors, or inaccessible content.

  • Content that is too large to cache, or problems exceeding your NetStorage usage limits.

  • Problems with edge computation such as Java exceptions, inaccessible application servers, and server reboots.

  • Badly distributed load-balanced content and SaaS application failovers.

  • Problems with Enhanced DNS such as expired zones and failed zone transfers.

  • Monitor overall changes to your Control Center configuration.

The API also allows you to configure all-purpose adaptive usage reports, even when not using alerting to detect specific problems.

Get started

Before using the Beta API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Alerts, and set the access level to READ-WRITE.

  • If you need help, provide feedback with the Akamai developer community, or else contact your Akamai representative for support.

Hypermedia

Throughout this API, Hypermedia links members allow automated client applications to navigate to relevant data and execute related operations.

This example from within a listing of template summaries provides a direct link to the API call necessary to access each template object, and describedBy JSON schema used to validate its contents:

{
    "links": [
        {
            "href": "/alerts/v2/alert-templates/s@1",
            "rel": "self"
        },
        {
            "href": "/alerts/v2/json-schema/alert-templates/s@1",
            "rel": "describedBy"
        }
    ]
}

In addition, href elements included within template fields indicate the availability of dynamic access control data. For example, this field definition references the API operation that lists the set of CP codes available to the client when you configure an alert:

{
    "default": [],
    "href": "/alerts/v2/access-control-data?type=cpcode&templateId=s@7",
    "itemType": "cpcode",
    "key": "aca_cpcode",
    "type": "multi-select"
}

Resources

The Alerts API allows you to configure notifications about significant changes to your traffic based on continual tracking by Akamai’s network monitoring platform. It allows you to create and modify alerts based on a wide range of criteria, and to configure reports on anomalies. This API provides you with a programmatic interface to the same functionality available in Control Center.

Here’s how to use the operations listed below, and how they correspond to object types detailed in the Data section.

  • Templates specify the kind of information necessary to configure different types of alert. Think of these as classes of alert that define what can kind of information can be monitored. These operations exchange the Template data object type.

  • Alerts, also known as definitions, are alert instances based on a template and configured to respond to a specific set of criteria. Alert definitions specify when the alert should fire, and who receives the notification. Criteria can be either static, involving fixed values, or adaptive, based on a dynamic predictive modeling of your web traffic patterns. This core set of CRUD operations exchange Definition object types.

  • Summaries and Details offer alternatively brief and verbose information about an alert. These operations generate corresponding Summary and Details object types.

  • Firings are periods of time when observed traffic meets an alert’s specified criteria, and include details on why the alert triggered. See the Firing object.

  • Suppressions specify known anomalous periods of time to ignore when dynamically modeling your traffic, to avoid training alerts on an unrepresentative set of data. See the Suppression object type.

  • Activities track changes to adaptive alert criteria over time, allowing you to compare when firings occurred to when changes were made to firing criteria. See the Activity object type.

  • Access Control Data is information dynamically available at run-time for use in configuring alerts. See the AccessControlData object type.

  • Sparklines are reports that overlay data for alert firings over a range of time. See the Sparkline object type.

  • Schema allow you to validate the contents of any of the other JSON objects the API exchanges. All schemas adhere to draft 4 of the JSON Schema standard.

  • Various availability checks confirm the services on which alerts depend are operating smoothly.

API summary

Operation Method Endpoint
Templates  
List Templates GET /alerts/v2/alert-templates/
Get a Template GET /alerts/v2/alert-templates/{templateId}
Alerts  
List Alerts GET /alerts/v2/alert-definitions{?fieldName,fieldValue,ids}
Create a New Alert POST /alerts/v2/alert-definitions
Get an Alert GET /alerts/v2/alert-definitions/{definitionId}
Update an Alert PUT /alerts/v2/alert-definitions/{definitionId}
Remove an Alert DELETE /alerts/v2/alert-definitions/{definitionId}
Get Adaptive Alert Edit History GET /alerts/v2/alert-definitions/{definitionId}/activities
Alert Firings  
List Active Firings GET /alerts/v2/alert-firings/active
List an Alert’s Firings GET /alerts/v2/alert-definitions/{definitionId}/alert-firings
Suppress Alert Modeling POST /alerts/v2/alert-definitions/{definitionId}/suppressions{?start,end}
List Modeling Suppressions GET /alerts/v2/alert-definitions/{definitionId}/suppressions
Unsuppress Alert Modeling DELETE /alerts/v2/alert-definitions/{definitionId}/suppressions/{suppressionId}
Access Control Data  
List Access Control Data GET /alerts/v2/access-control-data{?type,templateId,filter}
UI Helpers  
List Alert Summaries GET /alerts/v2/alert-summaries
Get an Alert Summary GET /alerts/v2/alert-summaries/{definitionId}
Get Alert Details GET /alerts/v2/alert-summaries/{definitionId}/details
Redirect GET /alerts/redirect{?type}
Sparklines  
List Sparklines GET /alerts/v2/sparklines{?definitionIds,duration,points,inclRange,adaptivecpcode,adaptivemetric}
Schema  
Get Template Header Schema GET /alerts/v2/json-schema/alert-template-header
Get Template Schema GET /alerts/v2/json-schema/alert-template
Get Definition Schema GET /alerts/v2/json-schema/alert-definition/{templateId}
Get Firings Schema GET /alerts/v2/json-schema/alert-firings
Get Summary Schema GET /alerts/v2/json-schema/alert-summaries
Get Details Schema GET /alerts/v2/json-schema/alert-details
Availability  
Check Access Control Data GET /alerts/v2/access-control-data/check
Check Definitions GET /alerts/v2/alert-definitions/check
Check Firings GET /alerts/v2/alert-firings/check
Check Summaries GET /alerts/v2/alert-summaries/check
Check Templates GET /alerts/v2/alert-templates/check
Check Schema GET /alerts/v2/json-schema/check
Check Sparklines GET /alerts/v2/sparklines/check

List templates

Lists templates for all supported alerts. Listed Template objects included in the response provide only high-level information about each alert template, such as its name and whether its origin is ADAPTIVE or STATIC. For a full definition that specifies all required fields, get a specific template instance.

GET /alerts/v2/alert-templates/

Status 200 application/json

Response:

{
    "data": [
        {
            "templateId": "s@1",
            "name": "High Traffic -- Content Delivery",
            "origin": "STATIC",
            "products": [
                {
                    "name": "Terra Alta Enterprise Accelerator",
                    "objectId": "Alta_alerts"
                },
                {
                    "name": "Terra Alta Enterprise Accelerator Fast File Upload",
                    "objectId": "Alta_ffu_alerts"
                },
                {
                    "name": "Adaptive Media Delivery",
                    "objectId": "AMD_alerts"
                },
                {
                    "name": "Akamai Cloud Catalyst",
                    "objectId": "Chamonix_alerts"
                },
                {
                    "name": "Akamai Cloud Catalyst Fast File Upload",
                    "objectId": "Chamonix_ffu_alerts"
                }
            ],
            "links": [
                { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-templates/s@1" },
                { "rel": "self", "href": "/alerts/v2/alert-templates/s@1" }
            ]
        },
        {
            "templateId": "s@134",
            "name": "SLA Availability",
            "origin": "STATIC",
            "products": [
                {
                    "name": "Terra Alta Enterprise Accelerator",
                    "objectId": "Alta_alerts"
                },
                {
                    "name": "Terra Alta Enterprise Accelerator Fast File Upload",
                    "objectId": "Alta_ffu_alerts"
                },
                {
                    "name": "Terra Alta Enterprise Accelerator SLA Management",
                    "objectId": "Alta_sa_alerts"
                },
                {
                    "name": "Terra Alta Enterprise Accelerator Composite Application Acceleration",
                    "objectId": "Alta_tpo_alerts"
                },
                {
                    "name": "Adaptive Media Delivery",
                    "objectId": "AMD_alerts"
                },
                {
                    "name": "Akamai Cloud Catalyst",
                    "objectId": "Chamonix_alerts"
                },
                {
                    "name": "Akamai Cloud Catalyst Fast File Upload",
                    "objectId": "Chamonix_ffu_alerts"
                }
            ],
            "links": [
                { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-templates/s@134" },
                { "rel": "self", "href": "/alerts/v2/alert-templates/s@134" }
            ]
        }
    ]
}

Get a template

Fetches a specific template. The response object features a full set of fields on which to base a new alert definition.

GET /alerts/v2/alert-templates/{templateId}

Example: /alerts/v2/alert-templates/s%40123

Parameter Type Sample Description
Required
templateId String s@123 Unique identifier for the template. Template origin types that are STATIC and ADAPTIVE are distinguished with s@ and a@ prefixes.

Status 200 application/json

Response:

{
    "templateId": "s@7",
    "name": "Origin Connection Failure",
    "origin": "STATIC",
    "fields": [
        {
            "default": "",
            "key": "name",
            "type": "string"
        },
        {
            "default": "",
            "key": "definitionId",
            "type": "hidden"
        },
        {
            "default": "s@7",
            "key": "templateId",
            "type": "hidden"
        },
        {
            "default": [],
            "href": "/alerts/v2/access-control-data?type=cpcode&templateId=s@7",
            "itemType": "cpcode",
            "key": "aca_cpcode",
            "type": "multi-select"
        },
        {
            "default": "both",
            "href": "/alerts/v2/access-control-data?type=network",
            "itemType": "network",
            "key": "network",
            "type": "single-select"
        },
        {
            "default": "cpercent",
            "key": "paramName",
            "type": "hidden"
        },
        {
            "default": 2,
            "key": "param",
            "label": "alertMeWhenOver",
            "maximum": 100,
            "minimum": 1,
            "sizeFloat": 2,
            "type": "float",
            "units": "percentOfTheConnectionsToTheOriginServerFail"
        },
        {
            "default": 0,
            "key": "alertLowerBound",
            "maximum": 999999,
            "minimum": 0,
            "type": "int",
            "units": "connections"
        },
        {
            "default": true,
            "key": "isSum",
            "type": "bool"
        },
        {
            "default": [],
            "key": "email",
            "type": "email"
        },
        {
            "default": [],
            "key": "emailBrief",
            "type": "email"
        },
        {
            "default": true,
            "key": "emailHtmlFormat",
            "type": "bool"
        },
        {
            "default": "",
            "key": "origVisibility",
            "type": "hidden"
        },
        {
            "default": "all",
            "href": "/alerts/v2/access-control-data?type=visibility",
            "itemType": "visibility",
            "key": "visibility",
            "type": "single-select"
        }
    ],
    "firingFields": [
        "cpCode", "cpCodeDescription", "hits", "errors",
        "alertConditionErrors", "alertThreshold", "edgeIp",
        "alertDelay", "emailTo"
    ],
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-templates/s@7" },
        { "rel": "self", "href": "/alerts/v2/alert-templates/s@7" }
    ]
}

  1. Run the List Templates operation.

  2. From the response object’s data array, choose the appropriate template for the alert.

  3. Store the Template object’s templateId.

  4. Make a GET request to /alerts/v2/alert-templates/{templateId}. The response is a Template object.

List alerts

Lists alert instances that are configured to fire under certain conditions. Optionally filter alerts by relevant fields or their values.

GET /alerts/v2/alert-definitions{?fieldName,fieldValue,ids}

Example: /alerts/v2/alert-definitions?fieldName=aca_cpcode&fieldValue=87525&ids=s%40123

Parameter Type Sample Description
Optional
fieldName String aca_cpcode Filter results to only include definitions that contain the specified field.
fieldValue String 87525 With fieldName specified, further filter results based on the field’s value. This matches either a scalar value or membership within an array.
ids String s@123 Filter results to include a subset, repeating the parameter to specify more than one definitionId identifier.

Status 200 application/json

Response:

{
    "data": [
        {
            "accountId": "1-ABE2981",
            "definitionId": "s@123",
            "editInfo": {
                "active": true,
                "createdAt": "2006-02-16T20:49:54Z",
                "createdBy": "anita",
                "editAt": "2006-02-16T20:49:54Z",
                "editBy": "deidrei"
            },
            "fields": {
                "aca_cpcode": [ "111", "87525" ],
                "alertLowerBound": 5,
                "definitionId": "s@123",
                "email": [ "nomail@akamai.com" ],
                "emailBrief": [ "12345678@akamai.com" ],
                "emailHtmlFormat": true,
                "isSum": true,
                "name": "myTestAlertName",
                "network": "myNetwork",
                "param": 20,
                "paramName": "cpercent",
                "templateId": "s@150"
            },
            "links": [
                { "rel": "describedBy", "href": "/alerts/v2/json-schema/templates/s@150/alert-definitions" },
                { "rel": "self", "href": "/alerts/v2/alert-definitions/s@123" }
            ],
            "origin": "STATIC"
        }
    ]
}

  1. Optionally set a relevant fieldName to search for. Results only include definitions whose fields contain the specified fieldName.

  2. If you set a fieldName, optionally set a corresponding fieldValue to filter results further. Results only include definitions field matches the value, or includes it within an array. For example, you can limit results to a specific CP code or email recipient.

  3. As an alternative to filtering by field, optionally set an ids to any definitionId value already available to you, repeating the parameter to specify more than one value in the subset.

  4. Make a GET request to /alerts/v2/alert-definitions{?fieldName,fieldValue,ids}. Alert Definition results appear in the response object’s data array.

Create a new alert

Create a new alert definition based on a template. The template’s required fields represent criteria you may use to trigger an alert, but the new definition’s fields specify the set of values that actually trigger the alert. After you create a new alert, it may take a couple of minutes before it has enough information before it can fire.

POST /alerts/v2/alert-definitions

Content-Type: application/json

Request:

{
    "definitionId": "",
    "origin": "STATIC",
    "fields": {
        "alertLowerBound": 5,
        "definitionId": "",
        "email": [ "nomail@akamai.com" ],
        "emailBrief": [ "12345678@akamai.com" ],
        "emailHtmlFormat": true,
        "group": [ "grp_123456" ],
        "isSum": true,
        "name": "myTestAlertName",
        "network": "myNetwork",
        "param": 20,
        "paramName": "cpercent",
        "templateId": "s@150",
        "aca_cpcode": [
            "111",
            "87525"
        ]
    }
}

Status 201 application/json

Response:

{
    "accountId": "1-ABE2981",
    "definitionId": "s@123",
    "editInfo": {
        "active": true,
        "createdAt": "2006-02-16T20:49:54Z",
        "createdBy": "joe12",
        "editAt": "2006-02-16T20:49:54Z",
        "editBy": "abby3"
    },
    "fields": {
        "aca_cpcode": [ "111", "87525" ],
        "alertLowerBound": 5,
        "definitionId": "s@123",
        "email": [ "nomail@akamai.com" ],
        "emailBrief": [ "12345678@akamai.com" ],
        "emailHtmlFormat": true,
        "isSum": true,
        "name": "myTestAlertName",
        "network": "myNetwork",
        "param": 20,
        "paramName": "cpercent",
        "templateId": "s@150"
    },
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/templates/s@150/alert-definitions" },
        { "rel": "self", "href": "/alerts/v2/alert-definitions/s@123" }
    ],
    "origin": "STATIC"
}

  1. Run the List Templates operation.

  2. From the response object’s data array, choose the appropriate template summary for the alert.

  3. Store the Template object’s templateId.

  4. Use the templateId to run the Get a Template operation and store the full Template object.

  5. Start forming a new definition request JSON object. Add a definitionId to the top level of the object, specifying a blank string value. (The member is required, but the value is supplied dynamically after you make the request.)

  6. Copy the origin from the template object to the definition request object.

  7. For each element in the template’s fields array, you need a key/value pair in the definition request’s fields object. Use its key for the member name, and base the value on the type. Most specialized types such as email represent string values, but others like multi-select require array values.

  8. The the field’s name member, specify a unique label to help you keep track of the alert.

  9. For the field’s definitionId member, supply a blank string value.

  10. For the field’s templateId member, supply the already stored value. This identifies the template to validate the contents of the fields.

  11. For any template field that features an href member, optionally use the link to access the set of values available to you at run-time. See the List Access Control Data operation for details.

  12. Once all the fields are specified, optionally run the Get Definition Schema operation to validate the request object against the JSON schema for definitions based on the given templateId.

  13. POST the request object to /alerts/v2/alert-definitions. The success response reflects the values back along with a definitionId key and set of relevant Hypermedia links.

Get an alert

Get a single alert instance that is configured to fire under certain conditions.

GET /alerts/v2/alert-definitions/{definitionId}

Example: /alerts/v2/alert-definitions/s%40123

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 200 application/json

Response:

{
    "accountId": "1-7CAFE",
    "corpAccount": "Akamai Test",
    "cpCode": 314159,
    "domain": "",
    "contractId": "1-3AB123",
    "templateId": "a@1",
    "definitionId": "a@cp_314159_1234",
    "origin": "ADAPTIVE",
    "services": "all",
    "fields": {
        "name": "YB-2 [Adaptive] IPA/SXL Mbps to User",
        "templateId": "a@1",
        "definitionId": "a@cp_314653_7198",
        "adaptivemetric": "srip_mbps_to_user",
        "adaptivecpcode": "314159",
        "adaptiveprofile": "17",
        "belowModel": {
            "deviations": 6,
            "windowSize": 32,
            "anomalyCount": 4
        },
        "aboveModel": {
            "deviations": 3,
            "windowSize": 4,
            "anomalyCount": 3
        },
        "email": [ "mtest@example.com" ]
    },
    "editInfo": {
        "createdAt": "2016-08-23T21:19:38.583Z",
        "createdBy": "",
        "editAt": "2016-08-23T21:19:38.583Z",
        "editBy": "",
        "active": true
    },
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/templates/a@1/alert-definitions" },
        { "rel": "self", "href": "/alerts/v2/alert-definitions/a@cp_314159_1234" }
    ],
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a GET request to /alerts/v2/alert-definitions/{definitionId}. The response is a Definition object.

Update an alert

Modify the criteria that determines when an alert fires. You must include the entire object in the request.

PUT /alerts/v2/alert-definitions/{definitionId}

Example: /alerts/v2/alert-definitions/s%40123

Content-Type: application/json

Request:

{
    "definitionId": "s@123",
    "fields": {
        "aca_cpcode": [ "111", "87525" ],
        "alertLowerBound": 5,
        "definitionId": "s@123",
        "email": [ "nomail@akamai.com" ],
        "emailBrief": [ "12345678@akamai.com" ],
        "emailHtmlFormat": true,
        "isSum": true,
        "name": "myTestAlertName",
        "network": "myNetwork",
        "param": 20,
        "paramName": "cpercent",
        "templateId": "s@150"
    },
    "origin": "STATIC"
}

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 204

  1. Run the Get an Alert operation.

  2. Modify the contents of the Definition response object’s fields to change the criteria under which the alert fires.

  3. Optionally run the List Accessible Content operation for fields that match any of the type parameters it supports. This gathers currently available values to modify the alert.

  4. Once you are finished modifying the object, PUT it to the same URL you used for the initial GET: /alerts/v2/alert-definitions/{definitionId}.

Remove an alert

Delete an alert and stop it from firing.

DELETE /alerts/v2/alert-definitions/{definitionId}

Example: /alerts/v2/alert-definitions/s%40123

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 204

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a DELETE request to /alerts/v2/alert-definitions/{definitionId}.

  5. A 204 response indicates successful deletion.

Get adaptive alert edit history

This operation lists changes to adaptive alerts, allowing you to compare changes over time to an alert’s firings with the criteria that triggered them.

GET /alerts/v2/alert-definitions/{definitionId}/activities

Example: /alerts/v2/alert-definitions/s%40123/activities

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 200 application/json

Response:

{
    "data": [
        {
            "activityId": 0,
            "details": "SERIES_DELETE",
            "startTime": "2015-04-11T06:03:15.820Z",
            "data": {}
        },
        {
            "activityId": 1,
            "details": "SERIES_ADD",
            "startTime": "2015-03-12T06:01:38.185Z",
            "data": {
                "id": null,
                "lastEdit": null,
                "aboveModelAlertDefinition": {
                    "anomalyCount": 7,
                    "uncertaintyFactor": 4,
                    "windowSize": 9
                },
                "belowModelAlertDefinition": {
                    "anomalyCount": 7,
                    "uncertaintyFactor": 4,
                    "windowSize": 9
                },
                "entity": {
                    "account": {
                        "id": "1-7KLGH",
                        "name": "Akamai Internal"
                    },
                    "cmp": false,
                    "description": "IPA Huawei trial",
                    "entityId": "351445",
                    "entityType": "cp"
                },
                "metric": {
                    "description": "IPA/SXL Mbps to User",
                    "id": 15,
                    "name": "srip_mbps_to_user"
                },
                "profile": {
                    "id": 13,
                    "name": "Weekly"
                }
            }
        }
    ]
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a GET request to /alerts/v2/alert-definitions/{definitionId}/activities. The response is a collection of Activity objects.

List active firings

List currently firing alerts for all alert definitions. Firings are arranged chronologically in the data array, with the most recent at the end.

GET /alerts/v2/alert-firings/active

Status 200 application/json

Response:

{
    "data": [
        {
            "firingId": "s@136523713",
            "definitionId": "s@175265",
            "name": "DNSSEC No DS record in parent",
            "startTime": "2016-06-02T07:21:18Z",
            "endTime": null,
            "service": "Edge DNS",
            "fieldMap": {
                "alertType": "No DS record in parent zone",
                "zone": "dnssec.akamaidemo.com",
                "emailTo": "dalawren@akamai.com"
            }
        },
        {
            "firingId": "s@140053407",
            "definitionId": "s@233655",
            "name": "New - Origin Object Not Found (HTTP 404 errors)",
            "startTime": "2016-10-28T03:45:34Z",
            "endTime": null,
            "service": "HTTP Content Delivery",
            "fieldMap": {
                "hits": "17",
                "cpCode": "130213",
                "alertConditionPctErrors": "22",
                "alertType": "Origin Object Not Found (HTTP 404 errors)",
                "alertThreshold": "5",
                "emailTo": "agoda-iat@akamai.com",
                "edgeIp": "96.17.180.42",
                "param1": "5",
                "errors": "4",
                "cpCodeDescription": "img.agoda.net"
            }
        },
        {
            "firingId": "s@140341187",
            "definitionId": "s@103155",
            "name": "Harmonie Web - Connection Failure",
            "startTime": "2016-11-07T20:55:06Z",
            "endTime": null,
            "service": "HTTP Content Delivery",
            "fieldMap": {
                "hits": "9",
                "cpCode": "16399",
                "alertConditionPctErrors": "33",
                "alertType": "Origin Connection Failure",
                "alertThreshold": "2",
                "emailTo": "jguest@akamai.com",
                "edgeIp": "104.86.110.115",
                "param1": "2",
                "errors": "3",
                "cpCodeDescription": "Akamai.Internal.3"
            }
        },
        {
            "firingId": "a@234929",
            "definitionId": "a@cp_140564_2672",
            "name": "cp 140564 Below model",
            "startTime": "2016-11-23T02:15:00Z",
            "endTime": null,
            "service": "all",
            "fieldMap": {
                "cpCode": "140564",
                "alertConditionBitsSec": "3750736.0",
                "accountName": "Akamai Technologies - Assets",
                "anomalyType": "Below model",
                "alertThresholdBitsSec": "1.64799595E7",
                "alertThresholdMbitsSec": "16.4799595",
                "expectedThresholdBitsSec": "6.3653717E7",
                "suppressed": false,
                "message": "cp 140564 Below model",
                "alertConditionMbitsSec": "3.750736",
                "expectedThresholdMbitsSec": "63.653717",
                "cpCodeDescription": "EIS - IPA CPCode"
            }
        },
        {
            "firingId": "a@235008",
            "definitionId": "a@cp_140564_2672",
            "name": "cp 140564 Above model",
            "startTime": "2016-11-23T21:00:00Z",
            "endTime": null,
            "service": "all",
            "fieldMap": {
                "cpCode": "140564",
                "alertConditionBitsSec": "1.36333084E8",
                "accountName": "Akamai Technologies - Assets",
                "anomalyType": "Above model",
                "alertThresholdBitsSec": "1.36189178E8",
                "alertThresholdMbitsSec": "136.189178",
                "expectedThresholdBitsSec": "9.58037033E7",
                "suppressed": false,
                "message": "cp 140564 Above model",
                "alertConditionMbitsSec": "136.333084",
                "expectedThresholdMbitsSec": "95.8037033",
                "cpCodeDescription": "EIS - IPA CPCode"
            }
        }
    ]
}

List alert firings

List a history of an alert definition’s firings. Firings for the most recent six months are arranged chronologically in the data array, with the most recent at the end. This lists alerts that have a defined endTime to indicate they are no longer in progress. For others, run the List Active Firings operation.

GET /alerts/v2/alert-definitions/{definitionId}/alert-firings

Example: /alerts/v2/alert-definitions/s%40123/alert-firings

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 200 application/json

Response:

{
    "data": [
        {
            "firingId": "9826198",
            "name": "Adaptive Alert",
            "definitionId": "a@12938",
            "service": "Mbps to User",
            "startTime": "2001-01-21T00:01:82.123Z",
            "endTime": "2001-01-21T02:21:12.002Z",
            "fieldMap": {
                "Account_Name": "Bob\u2019s Bait Inc",
                "Alert_Condition_(Mbits/sec)": "38.232",
                "Alert_Threshold_(Mbits/sec)": "32.12",
                "CP_Code": "1234",
                "CP_Code_Description": "Bob\u2019s Bait Shop \u2013 eStore",
                "Detail_URL": "https://control.akamai.com/tranquility/home#alert/102232/3267",
                "Expected_Value_(Mbits/sec)": "25.792",
                "Message": "Mbps to User: Above model",
                "alert_name_key": "Bob\u2019s Bait shop - EU - shopping cart (cp 1234) has above normal traffic",
                "email": "joy@bobsbait.com,juan@bobsbait.com",
                "suppressed": "true"
            }
        },
        {
            "firingId": "87238322",
            "name": "Security Monitor Aggregate Notification",
            "definitionId": "s@1524",
            "service": "dna",
            "startTime": "2001-01-21T00:01:82.123Z"
            "endTime": "2001-01-21T02:21:12.002Z",
            "fieldMap": {
                "Notification": "application layer attacks(id:2680)",
                "alert_name_key": "Security_Monitor Access Watch",
                "priority": "Medium",
                "trigger_time": "11/05/2015:22:39 GMT"
            }
        },
        {
            "firingId": "825394021",
            "name": "Customer Server Removed From Rotation",
            "definitionId": "s@1524",
            "service": "dna",
            "startTime": "2001-01-25T00:01:82.123Z"
            "endTime": null,
            "fieldMap": {
                "alert_name_key": "22221.02",
                "email_to": "guy_with_pager@example.com",
                "observed": "22221.02",
                "portal_link": "https://control.akamai.com/qos/SecMonServlet?notificationIds=1234&analyzerId=5678&startTime=11/05/2015:22:39&endTime=11/05/2015:22:39",
                "predicted": "6982.5",
                "trigger": "8138.34"
            }
        }
    ]
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a GET request to /alerts/v2/alert-definitions/{definitionId}/alert-firings. Firing objects are listed in the response’s data array.

Suppress alert modeling

This operation specifies a range of time for adaptive alerts to ignore when dynamically calculating a model of typical observed traffic and other behavior. For example, if a suddenly viral web asset results in a dramatic spike in traffic to your site, this operation ensures the period of increased traffic does not interfere with how your website’s ordinary expected level of traffic is modeled. You may specify a time range for the future if you anticipate a significant change to your traffic patterns. This operation only applies the ADAPTIVE alert type, and responds with an error if applied to any alert whose origin is STATIC.

POST /alerts/v2/alert-definitions/{definitionId}/suppressions{?start,end}

Example: /alerts/v2/alert-definitions/a%40123/suppressions?start=2001–01–25T00%3A01%3A82.123Z&end=2001–01–26T00%3A00%3A00.000Z

Parameter Type Sample Description
Required
definitionId String a@123 Unique identifier for the alert definition.
Optional
end String 2001-01-26T00:00:00.000Z Marks the end of the range of time at which an alert’s modeling is suppressed.
start String 2001-01-25T00:01:82.123Z Marks the start of the range of time at which an alert’s modeling is suppressed.

Status 201

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Determine the start and end of the period whose traffic you want to ignore, expressed as ISO 8601 timestamp strings.

  5. Make a POST request to /alerts/v2/alert-definitions/{definitionId}/suppressions{?start,end}. A 201 response indicates success.

List modeling suppressions

List all time ranges for an adaptive alert definition that are ignored when dynamically modeling its expected range of traffic. This operation only applies to adaptive alerts, and responds with an error if applied to a static alert.

GET /alerts/v2/alert-definitions/{definitionId}/suppressions

Example: /alerts/v2/alert-definitions/a%40123/suppressions

Parameter Type Sample Description
Required
definitionId String a@123 Unique identifier for the alert definition.

Status 200 application/json

Response:

{
    "data": [
        {
            "suppressionId": "2747",
            "start": "2015-11-12T21:15:00Z",
            "end": "2015-11-12T21:40:00Z"
        },
        {
            "suppressionId": "2755",
            "start": "2015-11-23T07:40:00Z",
            "end": "2015-11-23T08:40:00Z"
        },
        {
            "suppressionId": "2756",
            "start": "2015-12-21T17:40:00Z",
            "end": "2015-12-22T04:15:00Z"
        }
    ]
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a GET request to /alerts/v2/alert-definitions/{definitionId}/suppressions. The response’s data array lists Suppression objects.

Unsuppress alert modeling

Remove a suppression object. This makes an adaptive alert definition reconsider a previously suppressed period of time when modeling your site’s expected range of behavior. This operation only applies to adaptive alerts, and responds with an error if applied to a static alert. Suppressions that are too old to affect alert firings are automatically removed, so there is no need to run this operation simply to trim them from the list of modeling suppressions.

DELETE /alerts/v2/alert-definitions/{definitionId}/suppressions/{suppressionId}

Example: /alerts/v2/alert-definitions/a%40123/suppressions/12233

Parameter Type Sample Description
Required
definitionId String a@123 Unique identifier for the alert definition.
suppressionId String 12233 Unique identifier for the period of alert model suppression to be deleted

Status 200

  1. Run the List Modeling Suppressions operation.

  2. From the response object’s data array, select the Suppression object that represents the range of time you want to add back to the alert’s adaptive model.

  3. Store the object’s suppressionId.

  4. Make a DELETE request to /alerts/v2/alert-definitions/{definitionId}/suppressions/{suppressionId}.

List access control data

This operation lists items of relevant data available to you at runtime to apply to an alert definition. For example, when creating an alert about traffic levels for a set of CP codes, this operation allows you to list the set of CP codes to which you have access.

GET /alerts/v2/access-control-data{?type,templateId,filter}

Example: /alerts/v2/access-control-data?type=cpcode&templateId=s%40123&filter=available

Parameter Type Sample Description
Required
type Enumeration cpcode The type of access control data on which to report. Possible values: acggroup, adaptivecpcode, adaptivemetric, adaptiveprofile, arlfile, contract, cpcode, edns, eventlog, fpdomain, fpproperty, httpErrorCode, iphoneFileType, network, satest, slatest, sripslot, statest, stream, trigger, visibility.
Optional
filter String available When the type is set to slatest, specifies the ID to request, either available or performance.
templateId String s@123 When the type is cpcode, edns, stream, or httpErrorCode, restricts the range of data to what a specific template supports. For example, status codes in the 3xx range may not be relevant for a template that focuses on 4xx–5xx errors.

Status 200 application/json

Response:

{
    "data": [
        {
            "fields": { "timezone": null },
            "name": "Jabberwocky",
            "objectId": "44",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": null },
            "name": "Akamai Ads",
            "objectId": "79",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": null },
            "name": "64K - high bit flipped",
            "objectId": "126",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": null },
            "name": "Streaming disjointed",
            "objectId": "499",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": null },
            "name": "Streaming Metafile Servers",
            "objectId": "1054",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": null },
            "name": "Akamai Conference",
            "objectId": "1838",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": "-8" },
            "name": "Media Engineering NetStorage WSD",
            "objectId": "468062",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": "8" },
            "name": "Universal Streaming for multiplatform",
            "objectId": "468842",
            "type": "cpcode"
        }
    ]
}

  1. You would typically use this operation after running Get a Template and iterating through the template’s fields to build values for a Create a New Alert request.

  2. For any relevant field name prefixed with aca_, strip the prefix and store the field name as type.

  3. If the type is slatest, specify the filter parameter.

  4. If the type is cpcode or httpErrorCode, specify the templateId parameter.

  5. Make a GET request to /alerts/v2/access-control-data{?type,templateId,filter}. Within the response’s data array, the objectId of the AccessControlData object keys each data item.

This operation requires specifying a type query parameter. Each type of data you can report on corresponds to fields defined in various alert templates. The following types of data are available:

  • acggroup: ACG groups.
  • adaptivecpcode: Adaptive CP codes.
  • adaptivemetric: Adaptive metrics.
  • adaptiveprofile: Adaptive profiles.
  • arlfile: ARL files.
  • contract: Contracts.
  • cpcode: CP codes. Specifying an additional templateId parameter filters CP codes per template.
  • edns: Enhanced DNS zones.
  • eventlog: Eventlog events.
  • fpdomain: Firstpoint domains.
  • fpproperty: Firstpoint properties.
  • httpErrorCode: HTTP error codes. Requires an additional templateId to specify the appropriate template.
  • iphoneFileType: iPhone file types.
  • network: networks.
  • satest: Site Analyzer test.
  • slatest: SLA test data. Requires specifying an additional filter parameter value for availability or performance SLA data.
  • sripslot: SRIP slots.
  • statest: Stream analyser tests.
  • stream: Streams.
  • trigger: Stream trigger criteria.
  • visibility: Visibility options.

List alert summaries

Lists only high-level metadata about each alert: its name, ID, and when it was last fired. This operation wraps data available from other operations to generate simple, accessible listings.

GET /alerts/v2/alert-summaries

Status 200 application/json

Response:

{
    "data": [
        {
            "definitionId": "s@1623",
            "name": "High Traffic - production web portal",
            "lastTriggered": "2012-10-31T23:59:59Z",
            "links": [
                { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-summaries" },
                { "rel": "self", "href": "/alerts/v2/alert-summaries/s@1623" },
                { "rel": "details", "href": "/alerts/v2/alert-summaries/s@1623/details" }
            ]
        },
        {
            "definitionId": "s@1721",
            "name": "Stream outage",
            "lastTriggered": "2015-09-11T01:23:44Z",
            "links": [
                { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-summaries" },
                { "rel": "self", "href": "/alerts/v2/alert-summaries/s@1721" },
                { "rel": "details", "href": "/alerts/v2/alert-summaries/s@1721/details" }
            ]
        }
    ],
    "scopes": [
        "ALERTS_ADD",
        "ALERTS_EDIT",
        "ALERTS_HTML_EMAIL",
        "ALERTS_ORIGIN_CERT",
        "ALERTS_READ",
        "ALERTS_VIEWER",
        "ALERTS_DELETE"
    ]
}

Get an alert summary

Get the summary of basic metadata for a single alert.

GET /alerts/v2/alert-summaries/{definitionId}

Example: /alerts/v2/alert-summaries/s%40123

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 200 application/json

Response:

{
    "name": "High Traffic - production web portal",
    "definitionId": "s@1623",
    "lastTriggered": "2012-10-31T23:59:59Z",
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-summaries" },
        { "rel": "self", "href": "/alerts/v2/alert-summaries/s@1623" },
        { "rel": "details", "href": "/alerts/v2/alert-summaries/s@1623/details" }
    ]
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a GET request to /alerts/v2/alert-summaries/{definitionId}. The response is a Summary object.

Get alert details

Get verbose details for a single alert, including its definition, firings, and sparklines report.

GET /alerts/v2/alert-summaries/{definitionId}/details

Example: /alerts/v2/alert-summaries/s%40123/details

Parameter Type Sample Description
Required
definitionId String s@123 Unique identifier for the alert definition.

Status 200 application/json

Response:

{
    "definitionId": "s@17652",
    "definition": {
        "accountId": "1-7KLGH",
        "contractId": "1-5QRKWT",
        "corpAccount": "NONE",
        "cpCode": -1,
        "definitionId": "s@54257",
        "domain": null,
        "editInfo": {
            "active": true,
            "createdAt": "2007-10-16T22:11:19Z",
            "createdBy": "ed",
            "editAt": "2007-10-16T22:17:24Z",
            "editBy": "ana"
        },
        "fields": {
            "aca_satest": [ "25707", "25709", "25708" ],
            "definitionId": "s@54257",
            "email": [ "nomail@akamai.com" ],
            "emailBrief": [],
            "emailHtmlFormat": false,
            "isSum": false,
            "maintSchedule": null,
            "name": "apple_com_lma",
            "network": "sa",
            "origVisibility": "all",
            "param": 5,
            "paramName": "agents",
            "schedule": { "type": "schedule.all" },
            "templateId": "s@44",
            "visibility": "all"
        },
        "origin": "STATIC",
        "services": "sa",
        "templateId": "s@44"
    },
    "alerts": [],
    "sparkline": null,
    "scopes": [
        "ALERTS_ADD",
        "ALERTS_EDIT",
        "ALERTS_HTML_EMAIL",
        "ALERTS_ORIGIN_CERT",
        "ALERTS_READ",
        "ALERTS_VIEWER",
        "ALERTS_DELETE"
    ],
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/details" },
        { "rel": "summary", "href": "/alerts/v2/alert-summaries/s@17652" },
        { "rel": "self", "href": "/alerts/v2/alert-summaries/s@17652/details" }
    ]
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Make a GET request to /alerts/v2/alert-summaries/{definitionId}/details. The response is a Details object.

Redirect

A utility operation that redirects the client to the appropriate front-end Control Center interface, either for adaptive or static alerts, in case of outage or failover.

GET /alerts/redirect{?type}

Example: /alerts/redirect?type=adaptive

Parameter Type Sample Description
Optional
type String adaptive Specifies which legacy application redirect is for.

Status 307

Headers:

  • Location: /app/alerts/#/

List sparklines

Get a set of sparklines, reports that plot anomalies that trigger firings over a time series. Each sparkline this operation lists corresponds to an alert definition. Specifying more than one alert identifier allows you to gather related data from different alerts for potential use in overlays, for example one sparkline to identify too much traffic, and another for too little traffic.

Note that sparklines based on adaptive alerts provide observed data for both anomalies and the full range of points. Sparklines based on static alerts only provide observed data for anomalies, and the points simply define the range of the time series without any observed non-anomalous data.

GET /alerts/v2/sparklines{?definitionIds,duration,points,inclRange,adaptivecpcode,adaptivemetric}

Example: /alerts/v2/sparklines?definitionIds=a%4012938&duration=P7D&points=100&inclRange=false&adaptivecpcode=87525&adaptivemetric=mbps_to_user

Parameter Type Sample Description
Required
definitionIds String a@12938 Unique identifier for the alert to return sparklines for. Repeat the parameter to specify more than one alert.
Optional
adaptivecpcode String 87525 If you want to access raw data for an adaptive alert before its model has been created, this specifies the same CP code as when you first create the adaptive alert. Returned data only includes the raw y value with no high and low range.
adaptivemetric String mbps_to_user If you want to access raw data for an adaptive alert before its model has been created, this specifies the same data metric as when you first create the adaptive alert. Returned data only includes the raw y value with no high and low range.
duration String P7D Length of time prior to the current time for which to return data, expressed as ISO 8601 durations in PnDTnHnMn.nS format. The default value is P7D, or one week. Days are considered to be exactly 24 hours long, and duration values may be capped for improve performance.
inclRange Boolean false Whether to include high and low traffic predictions within data along with observed values. This only applies to adaptive alerts. The default is false.
points Number 100 The number of data points to include in the report, 100 by default. A value of 0 produces all available data.

Status 200 application/json

Response:

{
    "data": [
        {
            "definitionId": "a@17652",
            "anomalies": [
                {
                    "end": "2015-11-11T12:15:00Z",
                    "firingId": "9826198",
                    "start": "2015-11-09T16:50:00Z"
                },
                {
                    "firingId": "1989826",
                    "start": "2015-11-13T12:05:00Z"
                }
            ],
            "points": [
                {
                    "high": 5863.47,
                    "low": 3074.6,
                    "x": "2015-11-09T16:50:00Z",
                    "y": 4764.86
                },
                {
                    "high": 5995.18,
                    "low": 2940.94,
                    "x": "2015-11-09T16:55:00Z",
                    "y": 4731.73
                },
                {
                    "high": 5819.33,
                    "low": 3031.09,
                    "x": "2015-11-09T17:00:00Z",
                    "y": 4759.06
                },
                {
                    "high": 6137.78,
                    "low": 2790.63,
                    "x": "2015-11-09T17:05:00Z",
                    "y": 4749.52
                }
            ]
        }
    ]
}

  1. Run the List Alert Summaries operation.

  2. From the response object’s data array, select the appropriate object, for example, based on its name.

  3. Store the object’s definitionId.

  4. Optionally gather other definitionId values from related alert objects that fire based on the same criteria.

  5. Optionally set the duration back from the present time for which to gather data.

  6. Optionally set the number of separate points representing segments of data.

  7. Optionally for adaptive alerts, enable inclRange to include the expected range of high and low values for each observed data point.

  8. Make a GET request to /alerts/v2/sparklines{?definitionIds,duration,points,inclRange}. If listing sparklines for more than one alert, use repeated parameter syntax such as this: ?definitionIds=s@123&definitionIds=s@1524. The response’s data array contains Sparkline objects.

Get template header schema

Template headers are the abbreviated version of template objects that appear within collections. This operation gets the JSON schema that describes their contents.

GET /alerts/v2/json-schema/alert-template-header

Status 200 application/schema+json

Response:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Brief Summary of Alert template.",
    "properties": {
        "links": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "description": "Link relations to schemas and rest endpoints",
            "items": {
                "href": {
                    "description": "link to resource of type described by rel",
                    "type": "string"
                },
                "rel": {
                    "description": "Describes type of link",
                    "type": "string"
                }
            },
            "minItems": 2,
            "required": [ "rel", "href" ],
            "title": "Json link relations",
            "type": "array",
            "uniqueItems": true
        },
        "name": {
            "description": "name of template. not internationalized",
            "type": "string"
        },
        "origin": {
            "description": "name of system of record",
            "enum": [ "STATIC", "ADAPTIVE" ]
        },
        "templateId": {
            "description": "Id for template",
            "type": "string"
        }
    },
    "required": [ "templateId", "name", "origin", "links" ],
    "title": "Alert Template Header",
    "type": "object"
}

Get template schema

Gets the JSON schema that describes the contents of an alert template.

GET /alerts/v2/json-schema/alert-template

Status 200 application/schema+json

Response:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
        "abstractField": {
            "properties": {
                "description": {
                    "description": "text describing a field",
                    "type": "string"
                },
                "key": {
                    "description": "name or key of field",
                    "type": "string"
                }
            },
            "required": [ "key" ],
            "type": "object"
        },
        "abstractNumberField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "default": {
                            "description": "default value of field.  Used for fields with a single value.",
                            "type": "number"
                        },
                        "label": {
                            "description": "label tag associated with this field",
                            "type": "string"
                        },
                        "maximum": {
                            "description": "maximum allowed value",
                            "type": "number"
                        },
                        "minimum": {
                            "description": "minimum allowed value",
                            "type": "number"
                        },
                        "units": {
                            "description": "Describes unit type associated with the object",
                            "type": "string"
                        }
                    }
                }
            ],
            "description": "Represents a generic number field"
        },
        "abstractSelectField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "href": {
                            "description": "If present, represents a url where content for the field can be found.  This content is often complex and has been filtered due to users permissions.",
                            "type": "string"
                        },
                        "itemType": {
                            "description": "Describes type of objects returned by the endpoint",
                            "enum": [
                                "acg", "adaptivemetric", "adaptiveprofile",
                                "adaptivecpcode", "altatest", "arlfile", "arlid",
                                "chamonixtest", "contract", "cpcode", "drcpcode",
                                "dsatest", "edns", "eventlog", "fpdomain", "fpproperty",
                                "httpErrorCode", "ionhtest", "ionnatest", "ionrmtest",
                                "ionspmtest", "iphoneFile", "network", "roacontract",
                                "satest", "slatest", "sripslot", "statest",
                                "stream", "sxlslot", "trigger", "visibility", "waatest"
                            ]
                        }
                    },
                    "required": [ "itemType", "href" ]
                }
            ],
            "description": "Represents a field populated from an endpoint"
        },
        "adaptiveThresholdField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "jsonSchema": {
                            "description": "definition of fields the adaptive threshold must contain",
                            "type": "object"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "adaptive-threshold" ]
                        }
                    },
                    "required": [ "type", "jsonSchema" ]
                }
            ],
            "description": "Represents a set of adaptive alert thresholds field with value populated from an endpoint"
        },
        "booleanField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "default": {
                            "description": "default value of field.  Used for fields with a single boolean value.",
                            "type": "boolean"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "bool" ]
                        }
                    },
                    "required": [ "type", "default" ]
                }
            ],
            "description": "Represents a boolean value field"
        },
        "ednsField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "href_acg": {
                            "description": "Represents a url where acg content can be found.  This content is often complex and has been filtered due to users permissions. Only objectId is needed in the value array.",
                            "type": "string"
                        },
                        "href_edns": {
                            "description": "Represents a url where edns content can be found.  This content is often complex and has been filtered due to users permissions. Only objectId is needed in the value array.",
                            "type": "string"
                        },
                        "jsonSchema": {
                            "description": "stream json-schema representation",
                            "type": "object"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "edns" ]
                        }
                    },
                    "required": [ "type", "href_acg", "href_edns", "jsonSchema" ]
                }
            ],
            "description": "Represents a collection of acg or edns objects populated from specified multi-select endpoints"
        },
        "emailField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "default": {
                            "description": "Array of string values for field.",
                            "items": { "type": "string" },
                            "type": "array",
                            "uniqueItems": true
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "email" ]
                        }
                    },
                    "required": [ "type", "default" ]
                }
            ],
            "description": "Represents an email field"
        },
        "floatField": {
            "allOf": [
                { "$ref": "#/definitions/abstractNumberField" },
                {
                    "properties": {
                        "sizeFloat": {
                            "description": "number digits after zero",
                            "type": "number"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "float" ]
                        }
                    },
                    "required": [ "type" ]
                }
            ],
            "description": "Represents a float value field"
        },
        "integerField": {
            "allOf": [
                { "$ref": "#/definitions/abstractNumberField" },
                {
                    "properties": {
                        "type": {
                            "description": "field value type",
                            "enum": [ "int" ]
                        }
                    },
                    "required": [ "type" ]
                }
            ],
            "description": "Represents a integer value field"
        },
        "scheduleField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "jsonSchema": {
                            "description": "schedule json-schema representation",
                            "type": "object"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [
                                "schedule",
                                "maintenance-schedule"
                            ]
                        }
                    },
                    "required": [ "type" ]
                }
            ],
            "description": "Represents a schedule field"
        },
        "selectMultiValueField": {
            "allOf": [
                { "$ref": "#/definitions/abstractSelectField" },
                {
                    "properties": {
                        "default": {
                            "description": "Array of string values for field.",
                            "items": { "type": "string" },
                            "type": "array",
                            "uniqueItems": true
                        },
                        "maxItems": {
                            "description": "Maximum number of items required in array",
                            "type": "number"
                        },
                        "minItems": {
                            "description": "Minimum number of items required in array",
                            "type": "number"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "multi-select" ]
                        }
                    },
                    "required": [ "type", "default" ]
                }
            ],
            "description": "Represents a field with multiple values populated from an endpoint"
        },
        "selectSingleValueField": {
            "allOf": [
                { "$ref": "#/definitions/abstractSelectField" },
                {
                    "properties": {
                        "default": {
                            "description": "Single value for field",
                            "type": "string"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "single-select" ]
                        }
                    },
                    "required": [ "type", "default" ]
                }
            ],
            "description": "Represents a field with value populated from an endpoint"
        },
        "streamField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "href": {
                            "description": "If present, represents a url where content for the field can be found.  This content is often complex and has been filtered due to users permissions.",
                            "type": "string"
                        },
                        "jsonSchema": {
                            "description": "stream json-schema representation",
                            "type": "object"
                        },
                        "maxItems": {
                            "description": "Maximum number of items required in array",
                            "type": "number"
                        },
                        "minItems": {
                            "description": "Minimum number of items required in array",
                            "type": "number"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "stream" ]
                        }
                    },
                    "required": [ "type", "href", "jsonSchema" ]
                }
            ],
            "description": "Represents a collection of nameable streams with multiple values populated from an endpoint"
        },
        "stringField": {
            "allOf": [
                { "$ref": "#/definitions/abstractField" },
                {
                    "properties": {
                        "default": {
                            "description": "default value of field.  Used for fields with a single value.",
                            "type": "string"
                        },
                        "type": {
                            "description": "field value type",
                            "enum": [ "string", "hidden" ]
                        }
                    },
                    "required": [ "type", "default" ]
                }
            ],
            "description": "Represents a string value field"
        }
    },
    "description": "Alert template describing a type of alert that can be defined/configured for monitoring.",
    "properties": {
        "fields": {
            "description": "set of fields required to populate this template",
            "items": {
                "anyOf": [
                    { "$ref": "#/definitions/adaptiveThresholdField" },
                    { "$ref": "#/definitions/booleanField" },
                    { "$ref": "#/definitions/ednsField" },
                    { "$ref": "#/definitions/emailField" },
                    { "$ref": "#/definitions/floatField" },
                    { "$ref": "#/definitions/integerField" },
                    { "$ref": "#/definitions/scheduleField" },
                    { "$ref": "#/definitions/selectMultiValueField" },
                    { "$ref": "#/definitions/selectSingleValueField" },
                    { "$ref": "#/definitions/streamField" },
                    { "$ref": "#/definitions/stringField" }
                ]
            },
            "type": "array"
        },
        "firingFields": {
            "description": "array of alert fields associated with this template",
            "items": {
                "description": "field names expected in alert firing objects associated with this template (may change over time)",
                "type": "string"
            },
            "type": "array"
        },
        "links": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "description": "Link relations to schemas and rest endpoints",
            "items": {
                "href": {
                    "description": "link to resource of type described by rel",
                    "type": "string"
                },
                "rel": {
                    "description": "Describes type of link",
                    "type": "string"
                }
            },
            "minItems": 2,
            "required": [ "rel", "href" ],
            "title": "Json link relations",
            "type": "array",
            "uniqueItems": true
        },
        "name": {
            "description": "name of template. not internationalized",
            "type": "string"
        },
        "origin": {
            "description": "name of system of record",
            "enum": [ "STATIC", "ADAPTIVE" ]
        },
        "products": {
            "description": "array of products associated with this template",
            "items": {
                "description": "represents a CDN solution offering",
                "properties": {
                    "name": {
                        "description": "a basic description of content",
                        "type": "string"
                    },
                    "objectId": {
                        "description": "a unique identifier for this content",
                        "type": "string"
                    }
                },
                "required": [ "objectId", "name" ],
                "type": "object"
            },
            "type": "array"
        },
        "templateId": {
            "description": "Id for template",
            "type": "string"
        }
    },
    "required": [ "templateId", "name", "origin", "firingFields", "fields", "links" ],
    "title": "Alert Template",
    "type": "object"
}

Get definition schema

Gets the JSON schema that describes the contents of a specific type of alert, depending on the template used to create it. This is useful to validate the contents of a new alert request before POSTing it.

GET /alerts/v2/json-schema/alert-definition/{templateId}

Example: /alerts/v2/json-schema/alert-definition/s%407

Parameter Type Sample Description
Required
templateId String s@7 Unique identifier for the template for which the definition schema is requested. Since each template defines a different set of fields, the data requirements for alerts vary depending on the template.

Status 200 application/schema+json

Response:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Alert configured with thresholds for monitoring.",
    "links": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Link relations to schemas and rest endpoints",
        "items": {
            "href": {
                "description": "link to resource of type described by rel",
                "type": "string"
            },
            "rel": {
                "description": "Describes type of link",
                "type": "string"
            }
        },
        "minItems": 2,
        "required": [ "rel", "href" ],
        "title": "Json link relations",
        "type": "array",
        "uniqueItems": true
    },
    "properties": {
        "accountId": { "type": "string" },
        "definitionId": { "type": "string" },
        "editInfo": {
            "properties": {
                "active": { "type": "boolean" },
                "createdAt": {
                    "format": "date-time",
                    "type": "string"
                },
                "createdBy": { "type": "string" },
                "editAt": {
                    "format": "date-time",
                    "type": "string"
                },
                "editBy": { "type": "string" }
            },
            "required": [ "createdAt", "createdBy", "editAt", "editBy", "active" ],
            "type": "object"
        },
        "fields": {
            "properties": {
                "aca_cpcode": {
                    "items": "string",
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                },
                "alertLowerBound": {
                    "maximum": 999999,
                    "minimum": 0,
                    "type": "integer"
                },
                "definitionId": { "type": "string" },
                "email": {
                    "items": { "type": "string" },
                    "type": "array"
                },
                "emailBrief": {
                    "items": { "type": "string" },
                    "type": "array"
                },
                "emailHtmlFormat": { "type": "boolean" },
                "isSum": { "type": "boolean" },
                "name": { "type": "string" },
                "network": { "type": "string" },
                "origVisibility": { "type": "string" },
                "param": {
                    "maximum": 100,
                    "minimum": 1,
                    "type": "number"
                },
                "paramName": { "type": "string" },
                "templateId": { "type": "string" },
                "visibility": { "type": "string" }
            },
            "required": [
                "aca_cpcode", "alertLowerBound",
                "definitionId", "email", "emailBrief",
                "emailHtmlFormat", "isSum", "name", "network",
                "origVisibility", "param", "paramName",
                "templateId", "visibility"
            ],
            "type": "object"
        },
        "origin": {
            "description": "name of system of record",
            "enum": [ "STATIC", "ADAPTIVE" ]
        }
    },
    "required": [ "fields" ],
    "title": "AlertDefinition",
    "type": "object"
}

Get firings schema

Gets the JSON schema that describes the contents of an alert firing.

GET /alerts/v2/json-schema/alert-firings

Status 200 application/schema+json

Response:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Alert whose criteria were met with information on the state when the alert was activated.",
    "items": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "properties": {
            "definitionId": { "type": "string" },
            "endTime": {
                "format": "date-time",
                "type": "string"
            },
            "fieldMap": { "type": "object" },
            "firingId": { "type": "string" },
            "links": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "description": "Link relations to schemas and rest endpoints",
                "items": {
                    "href": {
                        "description": "link to resource of type described by rel",
                        "type": "string"
                    },
                    "rel": {
                        "description": "Describes type of link",
                        "type": "string"
                    }
                },
                "minItems": 2,
                "required": [ "rel", "href" ],
                "title": "Json link relations",
                "type": "array",
                "uniqueItems": true
            },
            "name": { "type": "string" },
            "service": { "type": "string" },
            "startTime": {
                "format": "date-time",
                "type": "string"
            }
        },
        "required": [ "firingId", "definitionId", "name", "startTime", "endTime", "service", "fieldMap" ],
        "type": "object"
    },
    "minItems": 0,
    "title": "List of fired alerts",
    "type": "array",
    "uniqueItems": true
}

Get summary schema

Gets the JSON schema that describes the contents of an alert summary.

GET /alerts/v2/json-schema/alert-summaries

Status 200 application/schema+json

Response:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Summary of configuration and recent firing information.",
    "items": {
        "properties": {
            "definitionId": { "type": "string" },
            "lastTriggered": {
                "format": "date-time",
                "type": "string"
            },
            "links": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "description": "Link relations to schemas and rest endpoints",
                "items": {
                    "href": {
                        "description": "link to resource of type described by rel",
                        "type": "string"
                    },
                    "rel": {
                        "description": "Describes type of link",
                        "type": "string"
                    }
                },
                "minItems": 2,
                "required": [ "rel", "href" ],
                "title": "Json link relations",
                "type": "array",
                "uniqueItems": true
            },
            "name": { "type": "string" }
        },
        "required": [ "definitionId", "name", "lastTriggered", "links" ],
        "type": "object"
    },
    "minItems": 0,
    "required": true,
    "title": "Alert Configuration Summary Helper Object",
    "type": "array",
    "uniqueItems": true
}

Get details schema

Gets the JSON schema that describes the contents of a verbose set of alert details.

GET /alerts/v2/json-schema/alert-details

Status 200 application/schema+json

Response:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Configuration details used together for presentation purposes.",
    "properties": {
        "alerts": {
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "description": "Alert whose criteria were met with information on the state when the alert was activated.",
                "items": {
                    "$schema": "http://json-schema.org/draft-04/schema#",
                    "properties": {
                        "definitionId": { "type": "string" },
                        "endTime": {
                            "format": "date-time",
                            "type": "string"
                        },
                        "fieldMap": { "type": "object" },
                        "firingId": { "type": "string" },
                        "links": {
                            "$schema": "http://json-schema.org/draft-04/schema#",
                            "description": "Link relations to schemas and rest endpoints",
                            "items": {
                                "href": {
                                    "description": "link to resource of type described by rel",
                                    "type": "string"
                                },
                                "rel": {
                                    "description": "Describes type of link",
                                    "type": "string"
                                }
                            },
                            "minItems": 2,
                            "required": [ "rel", "href" ],
                            "title": "Json link relations",
                            "type": "array",
                            "uniqueItems": true
                        },
                        "name": { "type": "string" },
                        "service": { "type": "string" },
                        "startTime": {
                            "format": "date-time",
                            "type": "string"
                        }
                    },
                    "required": [ "firingId", "definitionId", "name", "startTime", "endTime", "service", "fieldMap" ],
                    "type": "object"
                },
                "minItems": 0,
                "title": "List of fired alerts",
                "type": "array",
                "uniqueItems": true
            },
            "type": "array"
        },
        "definition": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "description": "Alert configured with thresholds for monitoring.",
            "links": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "description": "Link relations to schemas and rest endpoints",
                "items": {
                    "href": {
                        "description": "link to resource of type described by rel",
                        "type": "string"
                    },
                    "rel": {
                        "description": "Describes type of link",
                        "type": "string"
                    }
                },
                "minItems": 2,
                "required": [ "rel", "href" ],
                "title": "Json link relations",
                "type": "array",
                "uniqueItems": true
            },
            "properties": {
                "accountId": { "type": "string" },
                "definitionId": { "type": "string" },
                "editInfo": {
                    "properties": {
                        "active": { "type": "boolean" },
                        "createdAt": {
                            "format": "date-time",
                            "type": "string"
                        },
                        "createdBy": { "type": "string" },
                        "editAt": {
                            "format": "date-time",
                            "type": "string"
                        },
                        "editBy": { "type": "string" }
                    },
                    "required": [ "createdAt", "createdBy", "editAt", "editBy", "active" ],
                    "type": "object"
                },
                "fields": { "type": "object" },
                "origin": {
                    "description": "name of system of record",
                    "enum": [ "STATIC", "ADAPTIVE" ]
                }
            },
            "required": [ "fields" ],
            "title": "AlertDefinition",
            "type": "object"
        },
        "definitionId": { "type": "string" },
        "links": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "description": "Link relations to schemas and rest endpoints",
            "items": {
                "href": {
                    "description": "link to resource of type described by rel",
                    "type": "string"
                },
                "rel": {
                    "description": "Describes type of link",
                    "type": "string"
                }
            },
            "minItems": 2,
            "required": [ "rel", "href" ],
            "title": "Json link relations",
            "type": "array",
            "uniqueItems": true
        },
        "sparkline": {
            "$schema": "http://json-schema.org/draft-04/schema#",
            "description": "JSON used to represent graph data.  Amount of data varies with parameters supplied.",
            "properties": {
                "anomalies": {
                    "description": "Array of alert data associated with graph period",
                    "items": {
                        "properties": {
                            "end": {
                                "description": "End time of the anomaly.  If zero use the current time.",
                                "format": "date-time",
                                "type": "string"
                            },
                            "firingId": {
                                "description": "Alert firing id associated with this anomaly",
                                "type": "string"
                            },
                            "start": {
                                "description": "start time of the anomaly",
                                "format": "date-time",
                                "type": "string"
                            }
                        },
                        "required": [ "start", "firingId" ],
                        "title": "Alert instances",
                        "type": "object"
                    },
                    "type": "array"
                },
                "definitionId": {
                    "description": "a unique identifier for the associated alert definition",
                    "type": "string"
                },
                "points": {
                    "description": "Array of graph data for rendering traffic information.  Not always available.",
                    "items": {
                        "properties": {
                            "high": {
                                "description": "upper estimate",
                                "type": "number"
                            },
                            "low": {
                                "description": "lower estimate",
                                "type": "number"
                            },
                            "x": {
                                "description": "timestamp in ISO 8601 format",
                                "format": "date-time",
                                "type": "string"
                            },
                            "y": {
                                "description": "observed value",
                                "type": "number"
                            }
                        },
                        "required": [ "x", "y" ],
                        "title": "Datapoint",
                        "type": "object"
                    },
                    "type": "array"
                }
            },
            "required": [ "definitionId", "points", "anomalies" ],
            "title": "Sparkline",
            "type": "object"
        }
    },
    "required": [ "definitionId", "definition", "alerts", "links" ],
    "title": "Alert Details Helper Object",
    "type": "object"
}

Check access control data

Utility operation that confirms availability of the system that reports real-time access control data.

GET /alerts/v2/access-control-data/check

Status 204

Check definitions

Utility operation that confirms availability of alert definition data.

GET /alerts/v2/alert-definitions/check

Status 204

Check firings

Utility operation that confirms availability of alert firings data.

GET /alerts/v2/alert-firings/check

Status 204

Check summaries

Utility operation that confirms availability of alert summary data.

GET /alerts/v2/alert-summaries/check

Status 204

Check templates

Utility operation that confirms availability of alert template data.

GET /alerts/v2/alert-templates/check

Status 204

Check schema

Utility operation that confirms availability of alert schema data.

GET /alerts/v2/json-schema/check

Status 204

Check sparklines

Utility operation that confirms availability of alert sparkline data.

GET /alerts/v2/sparklines/check

Status 204

Data

This section describes all the types of data object the Alerts API exchanges. Whenever objects described here appear within a collection, an additional outer object wrapper lists them within a data array.

Template

Provides the full definition of an alert template, including fields you need to create a new alert.

Sample JSON response:

{
    "templateId": "s@7",
    "name": "Origin Connection Failure",
    "origin": "STATIC",
    "fields": [
        {
            "default": "",
            "key": "name",
            "type": "string"
        },
        {
            "default": "",
            "key": "definitionId",
            "type": "hidden"
        },
        {
            "default": "s@7",
            "key": "templateId",
            "type": "hidden"
        },
        {
            "default": [],
            "href": "/alerts/v2/access-control-data?type=cpcode&templateId=s@7",
            "itemType": "cpcode",
            "key": "aca_cpcode",
            "type": "multi-select"
        },
        {
            "default": "both",
            "href": "/alerts/v2/access-control-data?type=network",
            "itemType": "network",
            "key": "network",
            "type": "single-select"
        }
    ],
    "firingFields": [
        "cpCode", "cpCodeDescription", "hits", "errors", "alertConditionErrors",
        "alertThreshold", "edgeIp", "alertDelay", "emailTo"
    ],
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-templates/s@7" },
        { "rel": "self", "href": "/alerts/v2/alert-templates/s@7" }
    ],
    "products": [
        {
            "name": "Terra Alta Enterprise Accelerator",
            "objectId": "Alta_alerts"
        },
        {
            "name": "Terra Alta Enterprise Accelerator Fast File Upload",
            "objectId": "Alta_ffu_alerts"
        },
        {
            "name": "Terra Alta Enterprise Accelerator SLA Management",
            "objectId": "Alta_sa_alerts"
        },
    ]
}

Template members

Member Type Required Description
fields Template.fields[] ○ Lists the set of fields required to populate an alert based on this template. Does not appear within template collections.
firingFields Array ○ Lists field names that are expected to be reflected in a firing of an alert based on this template. Does not appear within template collections.
links Hypermedia ✓ Links to each template and the schema that describes it.
name String ✓ Name of the template.
origin Enumeration ✓ Identifies the type of alert the template enables, either STATIC or ADAPTIVE. Static alert types specify raw values, while the adaptive alert type expresses standard deviations. The only available ADAPTIVE alert identifies excessive traffic, and its templateId is a@1.
products Template.products[] ✓ Describes products associated with each template. You can only use the template if one of the products is on your contract.
templateId String ✓ Unique identifier for the template. Template origin types that are STATIC and ADAPTIVE are distinguished with s@ and a@ prefixes.
Template.fields[]
default n/a ○ The field’s default value, for use in a user interface. The data type varies depending on the field’s type.
href String ○ A hypermedia link to the dynamic access control data available for this field.
itemType String ○ Describes the content a type of single-select or multi-select manages, and which the associated href accesses.
key String ✓ The field’s unique identifier.
type Enumeration ✓ Identifies the semantic type of the field. Possible values are bool (boolean); float and int (numeric); string, single-select, and hidden (string); email and multi-select (array). Other object types are edns, stream, schedule, maintenance-schedule, and adaptive-threshold, which are all formally described in the template schema.
Template.products[]: Describes products associated with each template. You can only use the template if one of the products is on your contract.
name String ✓ The name of the product.
objectId String ✓ A unique product identifier.

Summary

Provides a high-level summary of an alert instance. The main Definition object provides the alert’s fields, and the Details object provides additional data on the alert’s firings and sparkline report.

Within collections of Summary objects, the same scopes member that appears for each alert in the Details object is placed at the top level of the collection, as a sibling of the data array.

Sample GET response:

{
    "name": "High Traffic - production web portal",
    "definitionId": "s@1623",
    "lastTriggered": "2012-10-31T23:59:59Z",
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/alert-summaries" },
        { "rel": "self", "href": "/alerts/v2/alert-summaries/s@1623" },
        { "rel": "details", "href": "/alerts/v2/alert-summaries/s@1623/details" }
    ]
}

Summary members

Member Type Required Description
definitionId String ✓ Unique identifier for each alert definition.
lastTriggered String ✓ ISO 8601 format timestamp for the most recent moment the alert was firing.
links Hypermedia ✓ Links to each alert and the schema that describes it.
name String ✓ Descriptive label for the alert.

Definition

Specifies an instance of an alert, including the fields that set the criteria under which it fires. Use this object rather than the alert Summary or Details when creating and modifying alerts.

This sample GET response shows an ADAPTIVE alert based on the a@1 template, which expresses variance in terms of standard deviations rather than fixed values used for STATIC origin types:

{
    "accountId": "1-7CAFE",
    "corpAccount": "Akamai Test",
    "cpCode": 314159,
    "domain": "",
    "contractId": "1-3AB123",
    "templateId": "a@1",
    "definitionId": "a@cp_314159_1234",
    "origin": "ADAPTIVE",
    "services": "all",
    "fields": {
        "name": "YB-2 [Adaptive] IPA/SXL Mbps to User",
        "templateId": "a@1",
        "definitionId": "a@cp_314653_7198",
        "adaptivemetric": "srip_mbps_to_user",
        "adaptivecpcode": "314159",
        "adaptiveprofile": "17",
        "belowModel": {
            "deviations": 6,
            "windowSize": 32,
            "anomalyCount": 4
        },
        "aboveModel": {
            "deviations": 3,
            "windowSize": 4,
            "anomalyCount": 3
        },
        "email": [ "mtest@example.com"]
    },
    "editInfo": {
        "createdAt": "2016-08-23T21:19:38.583Z",
        "createdBy": "",
        "editAt": "2016-08-23T21:19:38.583Z",
        "editBy": "",
        "active": true
    },
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/templates/a@1/alert-definitions" },
        { "rel": "self", "href": "/alerts/v2/alert-definitions/a@cp_314159_1234" }
    ],
}

Definition members

Member Type Required Description
accountId String ✓ Unique identifier for the account under which the alert was created.
definitionId String ✓ Unique identifier for each alert definition.
editInfo Definition.editInfo ✓ A summary of the alert’s creation time and most recent edit.
fields Object ✓ The set of criteria that determines when the alert fires. The object’s members vary depending on the template on which the alert is based. However, all fields include a name, the templateId on which the alert was based, and an array of email addresses for the alert’s recipients.
links Hypermedia ✓ Links to the alert and the schema that describes it.
origin Enumeration ✓ Identifies the type of alert the template enables, either STATIC or ADAPTIVE. Static alert types specify raw values, while the adaptive alert type expresses standard deviations. The only available ADAPTIVE alert identifies excessive traffic, and its templateId is a@1.
Definition.editInfo: A summary of the alert’s creation time and most recent edit.
active Boolean ✓ When the alert origin is STATIC, indicates if the alert is allowed to fire. A false value may be due to variations in account and contract status that leaves the alert configured but inactive.
createdAt String ✓ ISO 8601 timestamp for when the alert was created.
createdBy String ✓ The user who created the alert.
editAt String ✓ ISO 8601 timestamp for when the alert was last edited.
editBy String ✓ The user who last edited the alert.

Details

Provides verbose information about an alert instance: not only its main fields definition, but its history of firings and a sparkline report.

Sample GET response:

{
    "definitionId": "s@17652",
    "definition": {
        "accountId": "1-7KLGH",
        "contractId": "1-5QRKWT",
        "corpAccount": "NONE",
        "cpCode": -1,
        "definitionId": "s@54257",
        "domain": null,
        "editInfo": {
            "active": true,
            "createdAt": "2007-10-16T22:11:19Z",
            "createdBy": "ed",
            "editAt": "2007-10-16T22:17:24Z",
            "editBy": "ana"
        },
        "fields": {
            "aca_satest": [ "25707", "25709", "25708" ],
            "definitionId": "s@54257",
            "email": [ "nomail@akamai.com" ],
            "emailBrief": [],
            "emailHtmlFormat": false,
            "isSum": false,
            "maintSchedule": null,
            "name": "apple_com_lma",
            "network": "sa",
            "origVisibility": "all",
            "param": 5,
            "paramName": "agents",
            "schedule": { "type": "schedule.all" },
            "templateId": "s@44",
            "visibility": "all"
        },
        "origin": "STATIC",
        "services": "sa",
        "templateId": "s@44"
    },
    "scopes": [
        "ALERTS_ADD",
        "ALERTS_EDIT",
        "ALERTS_HTML_EMAIL",
        "ALERTS_ORIGIN_CERT",
        "ALERTS_READ",
        "ALERTS_VIEWER",
        "ALERTS_DELETE"
    ],
    "alerts": [],
    "sparkline": null,
    "links": [
        { "rel": "describedBy", "href": "/alerts/v2/json-schema/details" },
        { "rel": "summary", "href": "/alerts/v2/alert-summaries/s@17652" },
        { "rel": "self", "href": "/alerts/v2/alert-summaries/s@17652/details" }
    ]
}

Details members

Member Type Required Description
alerts Firing Array ✓ A full history the alert’s firings.
definition Definition ✓ Encapsulates the criteria under which the alert fires and who is notified.
definitionId String ✓ Unique identifier for each alert definition.
links Hypermedia ✓ Links to the alert and the schema that describes it.
scopes Array ✓ Describes the user’s permission to modify the alert, represented as the following set of enumerated values: ALERTS_READ, ALERTS_ADD, ALERTS_DELETE, ALERTS_EDIT, ALERTS_HTML_EMAIL, ALERTS_ORIGIN_CERT, and ALERTS_VIEWER.
sparkline Sparkline ○ Basic sparkline report data for the alert, the same as when using default values to call the List Sparklines operation. Only available for adaptive alerts.

Activity

This object encapsulates changes over time to an adaptive alert’s firing criteria.

Sample GET response:

{
    "data": [
        {
            "activityId": 0,
            "details": "SERIES_DELETE",
            "startTime": "2015-04-11T06:03:15.820Z",
            "data": {}
        },
        {
            "activityId": 1,
            "details": "SERIES_ADD",
            "startTime": "2015-03-12T06:01:38.185Z",
            "data": {
                "id": null,
                "lastEdit": null,
                "aboveModelAlertDefinition": {
                    "anomalyCount": 7,
                    "uncertaintyFactor": 4,
                    "windowSize": 9
                },
                "belowModelAlertDefinition": {
                    "anomalyCount": 7,
                    "uncertaintyFactor": 4,
                    "windowSize": 9
                },
                "entity": {
                    "account": {
                        "id": "1-7KLGH",
                        "name": "Akamai Internal"
                    },
                    "cmp": false,
                    "description": "IPA Huawei trial",
                    "entityId": "351445",
                    "entityType": "cp"
                },
                "metric": {
                    "description": "IPA/SXL Mbps to User",
                    "id": 15,
                    "name": "srip_mbps_to_user"
                },
                "profile": {
                    "id": 13,
                    "name": "Weekly"
                }
            }
        }
    ]
}

Activity members

Member Type Required Description
activityId Number ✓ Unique integer identifier for the change to the adaptive alert.
data Object ○ A contextual object that specifies the new set of values for alert fields that have changed.
details String ✓ Characterizes the type of change to the adaptive alert.
startTime String ✓ ISO 8601 timestamp for when the change to the adaptive alert occurred.

Firing

Captures relevant state information when an alert’s criteria are met.

Sample GET response, showing a single firing within a data collection:

{
    "data": [
        {
            "firingId": "9826198",
            "name": "Adaptive Alert",
            "definitionId": "a@12938",
            "service": "Mbps to User",
            "startTime": "2001-01-21T00:01:82.123Z",
            "endTime": "2001-01-21T02:21:12.002Z",
            "fieldMap": {
                "Account_Name": "Bob\u2019s Bait Inc",
                "Alert_Condition_(Mbits/sec)": "38.232",
                "Alert_Threshold_(Mbits/sec)": "32.12",
                "CP_Code": "1234",
                "CP_Code_Description": "Bob\u2019s Bait Shop \u2013 eStore",
                "Detail_URL": "https://control.akamai.com/tranquility/home#alert/102232/3267",
                "Expected_Value_(Mbits/sec)": "25.792",
                "Message": "Mbps to User: Above model",
                "alert_name_key": "Bob\u2019s Bait shop - EU - shopping cart (cp 1234) has above normal traffic",
                "email": "joy@bobsbait.com,juan@bobsbait.com",
                "suppressed": "true"
            }
        }
    ]
}

Firing members

Member Type Required Description
definitionId String ✓ Unique identifier for each alert definition.
endTime String ○ ISO 8601 timestamp for the period ending when the alert fired, corresponding to startTime. The value is null if the alert is currently firing.
fieldMap Object ✓ A free-form object that captures details on state when the alert triggered, akin to a stack trace.
firingId String ✓ Unique identifier for each alert firing.
name String ✓ Name of the alert that fired.
service String ✓ Identifies the back-end service provider that fired the alert.
startTime String ✓ ISO 8601 timestamp for the period starting when the alert fired, corresponding to endTime.

Suppression

Alert suppressions define anomalous periods of time to ignore when modeling your site’s typical traffic patterns for an adaptive alert.

A sample GET response, whose data lists all suppressed time ranges:

{
    "data": [
        {
            "suppressionId": "2747",
            "start": "2015-11-12T21:15:00Z",
            "end": "2015-11-12T21:40:00Z"
        },
        {
            "suppressionId": "2755",
            "start": "2015-11-23T07:40:00Z",
            "end": "2015-11-23T08:40:00Z"
        },
        {
            "suppressionId": "2756",
            "start": "2015-12-21T17:40:00Z",
            "end": "2015-12-22T04:15:00Z"
        }
    ]
}

Suppression members

Member Type Required Description
end String ✓ Defines the end of the suppressed time range.
start String ✓ Defines the start of the suppressed time range.
suppressionId String ✓ Unique identifier for the suppressed time range.

Sparkline

Represents a graph of observed data up to the present time. The amount of data varies depending on the parameters used to generate it.

Sample GET response:

{
    "data": [
        {
            "definitionId": "a@17652",
            "anomalies": [
                {
                    "end": "2015-11-11T12:15:00Z",
                    "firingId": "9826198",
                    "start": "2015-11-09T16:50:00Z"
                },
                {
                    "firingId": "9898261",
                    "start": "2015-11-13T12:05:00Z"
                }
            ],
            "points": [
                {
                    "high": 5863.47,
                    "low": 3074.6,
                    "x": "2015-11-09T16:50:00Z",
                    "y": 4764.86
                },
                {
                    "high": 5995.18,
                    "low": 2940.94,
                    "x": "2015-11-09T16:55:00Z",
                    "y": 4731.73
                },
                {
                    "high": 5819.33,
                    "low": 3031.09,
                    "x": "2015-11-09T17:00:00Z",
                    "y": 4759.06
                },
                {
                    "high": 6137.78,
                    "low": 2790.63,
                    "x": "2015-11-09T17:05:00Z",
                    "y": 4749.52
                }
            ]
        }
    ]
}

Sparkline members

Member Type Required Description
anomalies Sparkline.anomalies[] ○ Lists alert firings that occur within the report’s time range.
definitionId String ✓ Unique identifier for each alert definition.
points Sparkline.points[] ○ Encapsulates the full range of graph data used to render traffic information.
Sparkline.anomalies[]: Lists alert firings that occur within the report’s time range.
end String ○ ISO 8601 timestamp for when the anomaly ended, or null for a currently firing anomaly.
firingId String ✓ Unique identifier for the alert firing associated with this anomaly.
start String ✓ ISO 8601 timestamp for when the anomaly started.
Sparkline.points[]: Encapsulates the full range of graph data used to render traffic information.
high Number ○ Upper bound of expected value. Only available for adaptive alerts.
low Number ○ Lower bound of expected value. Only available for adaptive alerts.
x String ✓ ISO 8601 timestamp for each data point.
y Number ✓ For adaptive alerts, provides the observed value at that point. Otherwise yields 0 for static alerts, in which case x values simply define the overall range of the time series.

AccessControlData

Represents access controlled data available at runtime for use in configuring alert firing criteria.

Sample GET response:

{
    "data": [
        {
            "fields": { "timezone": null },
            "name": "Jabberwocky",
            "objectId": "44",
            "type": "cpcode"
        },
        {
            "fields": { "timezone": null },
            "name": "64K - high bit flipped",
            "objectId": "126",
            "type": "cpcode"
        }
    ]
}

AccessControlData members

Member Type Required Description
fields AccessControlData.fields[] ○ Lists additional properties that describe the accessible data.
name String ✓ The name of the accessible item accessed.
objectId String ✓ A unique identifier for the accessible item.
type Enumeration ✓ Type of access control data. Possible values: acggroup, adaptivecpcode, adaptivemetric, adaptiveprofile, arlfile, contract, cpcode, edns, eventlog, fpdomain, fpproperty, httpErrorCode, iphoneFileType, network, satest, slatest, sripslot, statest, stream, trigger, or visibility. See the List Access Control Data operation for details.
AccessControlData.fields[]: Lists any additional properties that characterize the accessible data.
key String ✓ Unique key for the additional data.
value String ✓ Corresponding value for each key.

Errors

When you encounter an error, the Alerts API responds with HTTP Problem objects that provide details useful for debugging, as in the example below. In some cases, 502 or 503 routing errors may respond with HTML generated from the application server.

{
    "detail": "java.lang.IllegalArgumentException: Not a valid Id"
}

HTTP status codes

The Alerts API responds with the following range of status codes:

Code Description
200 Request OK.
201 Successfully created.
204 Successfully updated or deleted.
400 Badly formatted JSON, invalid or missing input data.
401 Platform error, likely an expired or missing token.
403 Application permission error.
404 Content unavailable or inaccessible.
500 Internal error. See JSON error response for details.
502 Platform timeout error.
503 Unspecified platform error.