Alerts API 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 Description
Required
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.[n] 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.
Optional
fields Template.fields.[n] 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.

Template.fields.[n]  

Member Type Description
Required
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.
Optional
default n/a The field’s default value, for use in a user interface. The data type varies depending on the field’s type.
itemType String Describes the content a type of single-select or multi-select manages, and which the associated href accesses.
href String A hypermedia link to the dynamic access control data available for this field.

Template.products.[n]  

Describes products associated with each template. You can only use the template if one of the products is on your contract.

Member Type Description
Required
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 Description
Required
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 Description
Required
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.

Member Type Description
Required
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 Description
Required
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.
Optional
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 Description
Required
activityId Number Unique integer identifier for the change to the adaptive alert.
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.
Optional
data Object A contextual object that specifies the new set of values for alert fields that have changed.

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 Description
Required
definitionId String Unique identifier for each alert definition.
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.
Optional
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.

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 Description
Required
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 Description
Required
definitionId String Unique identifier for each alert definition.
Optional
anomalies Sparkline.anomalies.[n] Lists alert firings that occur within the report’s time range.
points Sparkline.points.[n] Encapsulates the full range of graph data used to render traffic information.

Sparkline.anomalies.[n]  

Lists alert firings that occur within the report’s time range.

Member Type Description
Required
firingId String Unique identifier for the alert firing associated with this anomaly.
start String ISO 8601 timestamp for when the anomaly started.
Optional
end String ISO 8601 timestamp for when the anomaly ended, or null for a currently firing anomaly.

Sparkline.points.[n]  

Encapsulates the full range of graph data used to render traffic information.

Member Type Description
Required
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.
Optional
high Number Upper bound of expected value. Only available for adaptive alerts.
low Number Lower bound of expected value. Only available for adaptive alerts.

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 Description
Required
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.
Optional
fields AccessControlData.fields.[n] Lists additional properties that describe the accessible data.

AccessControlData.fields.[n]  

Lists any additional properties that characterize the accessible data.

Member Type Description
Required
key String Unique key for the additional data.
value String Corresponding value for each key.

Last modified: 12/6/2016