Learn more:

• Prolexic

• Prolexic Analytics API v1

• Download this API’s RAML and JSON schema descriptors.

Overview

The Prolexic Analytics API exposes analytics data from Prolexic DDoS protection and monitoring services such as alerts and network bandwidth timeseries data.

Who should use this API

The Prolexic Analytics API helps you better integrate Prolexic’s data into your local environment. You can track network usage and review traffic spikes during attacks using timeseries data. You can also pull attack reports and alert information into local SIEM instances to streamline emergency response and post-event triage using events data.

Get started

To configure this 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 Prolexic Analytics API, and set the access level to READ-ONLY.

API concepts

To understand this API’s various URL resources and the data it exchanges, familiarize yourself with these concepts:

• Metrics: Metrics contain telemetry collected from Akamai networks or your flow-based monitoring (FBM) netflow exports.

• Metric types: Metric types encapsulate the available types of data from the metrics endpoint.

• Attack reports: Attack reports created by the SOCC regarding attack events of interest that occur within your traffic.

• Events: A list of security events with information on the location of the event and additional attack information.

• Critical events: A list of security events marked with the highest level severity.

• Time series: Time series usage and attack data for individual destination IP addresses.

Data facet syntax

This API’s Get time series data operation returns a three-level mapping structure with details about usage and attacks on individual destination IP addresses or CIDR blocks.

In the operation’s response, you can see numerous usage timestamps corresponding to individual data facets. A data facet can have one of these formats:

• [ACCESS|BORDER]_FLOW_[DATA_CENTER_NAME]_[NETWORK_PROTOCOL|TOTAL]_[BPS|PPS]

• [ACCESS|BORDER]_FLOW_[NETWORK_PROTOCOL|TOTAL]_[BPS|PPS]

This table shows sample values you may see in a response together with explanations of specific segments:

Rate limiting

Prolexic Analytics API endpoints are subject to a rate-limiting constraint, which is currently set to 1000 requests per hour. When this limit is reached, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop. This is consistent with all protected Akamai assets exposed via API calls.

Resources

This section provides details on each API operation.

API summary

Download the RAML descriptors for this API.

Get metrics data

Lists metrics specified in the type object, falling between given start and end times, sampled at the given rate and attached to given contract. The maximum range between start and end is 90 days.

If some (not all) requested types are invalid, invalid types are silently dropped, and the response only contains data for valid requests. More meaningful errors result if you are requesting data for only one type at a time.

{
    "contract": "venus",
    "start": 1322390037,
    "end": 1400385899,
    "samples": 100,
    "type": {
        "routed": [
            "bandwidthIn"
        ],
        "fbm": [
            {
                "metric": "bandwidth",
                "protocol": "total",
                "subnet": "1.1.1.0/24"
            },
            {
                "metric": "packets",
                "protocol": "tcp",
                "ip": "1.1.1.10"
            }
        ]
    }
}

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Metrics acquired successfully",
    "data": [
        {
            "service": "routed",
            "metric": "bandwidthIn",
            "points": [
                [
                    1392609960,
                    211014
                ],
                [
                    1396886760,
                    202529
                ]
            ]
        },
        {
            "service": "fbm",
            "metric": "bandwidthIn",
            "protocol": "total",
            "subnet": "1.1.1.0/24",
            "points": [
                [
                    1392609960,
                    211014
                ],
                [
                    1396886760,
                    202529
                ]
            ]
        },
        {
            "service": "routed",
            "metric": "bandwidthIn",
            "protocol": "tcp",
            "ip": "1.1.1.10",
            "points": [
                [
                    1392609960,
                    211014
                ],
                [
                    1396886760,
                    202529
                ]
            ]
        }
    ]
}

List metric types

Retrieve a list of metric types for a specific customer.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Metric Types list acquired successfully",
    "data": {
        "routed": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "connect": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound packets, packets per second"
                }
            }
        },
        "mitigationPost": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "proxy": {
            "metrics": {
                "latency": {
                    "desc": "Average latency of request"
                },
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "bandwidthOut": {
                    "desc": "Customer outbound traffic, bits per second"
                },
                "connections": {
                    "desc": "Connections count"
                },
                "packetsOut": {
                    "desc": "Customer outbound traffic, packets per second"
                },
                "requests": {
                    "desc": "Requests count"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "mitigationPre": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "fbm": {
            "metrics": {
                "bandwidth": {
                    "desc": "Customer traffic bits per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                },
                "packets": {
                    "desc": "Customer traffic packets per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                }
            }
        }
    }
}

List attack reports

Retrieves a list of attack reports for a customer within the specified time range.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Attack reports acquired successfully",
    "data": [
        {
            "attackId": 2985,
            "destinationPort": "80",
            "eventStartTime": 1381320180,
            "ticketId": 97585,
            "eventEndTime": 1381349454,
            "eventStartTimeAsString": "2013-10-09 12:03:00",
            "endTime": 1381363451,
            "eventId": 4202,
            "eventEndTimeAsString": "2013-10-09 20:10:54",
            "startTime": 1381063041,
            "eventTypes": [
                "DNS Flood",
                "ICMP Flood",
                "UDP Fragment"
            ],
            "peaks": [
                {
                    "location": "DCA",
                    "peakId": 17277,
                    "bandwidth": 6500000000,
                    "pps": 700000
                },
                {
                    "location": "HKG",
                    "peakId": 17276,
                    "bandwidth": 3000000000,
                    "pps": 600000
                }
            ],
            "destinations": [
                {
                    "netmask": 32,
                    "ip": "178.132.240.100"
                },
                {
                    "netmask": 32,
                    "ip": "178.132.240.155"
                }
            ]
        },
        {
            "attackId": 2974,
            "destinationPort": "80",
            "eventStartTime": 1380714180,
            "ticketId": 97368,
            "eventEndTime": 1380752215,
            "eventStartTimeAsString": "2013-10-02 11:43:00",
            "endTime": 1380847367,
            "eventId": 4170,
            "eventEndTimeAsString": "2013-10-02 22:16:55",
            "startTime": 1380714180,
            "eventTypes": [
                "SYN Flood"
            ],
            "peaks": [
                {
                    "location": "DCA",
                    "peakId": 17093,
                    "bandwidth": 300000000,
                    "pps": 200
                },
                {
                    "location": "HKG",
                    "peakId": 17092,
                    "bandwidth": 3000000,
                    "pps": 1000
                }
            ],
            "destinations": [
                {
                    "netmask": 32,
                    "ip": "178.132.240.126"
                }
            ]
        }
    ]
}

Get an attack report

Retrieves an attack report for the specified customer and attackId.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Attack report acquired successfully",
    "data": [
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18594,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "SJC",
            "endTime": 1390261538,
            "eventBw": 500000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 1200,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        },
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18595,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "LON",
            "endTime": 1390261538,
            "eventBw": 90000000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 200000,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        }
    ]
}

List events

Retrieves an events list for a customer.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully",
    "data": [
        {
            "service": "man",
            "eventType": "alert",
            "isOngoing": false,
            "eventStartTime": 1390975985,
            "eventTitle": "chkInt: Interface GigabitEthernet0/18 is down.",
            "severity": 80,
            "eventEndTime": 1393236546,
            "eventInfo": {
                "location": "mia1",
                "lastOccurred": 1393236546,
                "attackId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems"
            }
        },
        {
            "service": "Mitigation",
            "eventType": "attack",
            "isOngoing": true,
            "eventStartTime": 1392922838,
            "eventTitle": "[\"SYN Flood\"]",
            "severity": 100,
            "eventEndTime": 0,
            "eventInfo": {
                "eventTicketId": "70167",
                "attackType": "[\"SYN Flood\"]",
                "endTime": false,
                "attackEventId": "2707",
                "destinationIPs": "[178.132.240.114/32, 178.132.240.155/32, 178.132.240.203/32]",
                "startTime": 1392922838
            }
        }
    ]
}

List critical events

Retrieves a critical events list for a customer.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully",
    "data": [
        {
            "siteType": "DC",
            "source": "wbm",
            "location": "dca1",
            "ip": "192.216.61.102",
            "summary": "WBM TEST 5",
            "instance": "01",
            "interfaceName": "unknown",
            "count": 11,
            "siteCustomerName": "coral",
            "eventId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems",
            "siteName": "dca1",
            "acknowledged": 0,
            "state": 1,
            "recentOccur": 1395842910,
            "expires": 3600,
            "node": "lr1.dca1.plx",
            "importance": 5,
            "notes": "TEST 5",
            "firstOccur": 1393657985,
            "description": "TEST WBM LEVEL 5"
        }
    ]
}

Get time series data

Lists usage and attack information for individual destination IP addresses. Optionally specify the startTime and endTime to get data from a specific period. The maximum date range is the last seven days. By default you get data from the last two hours. Specify locations to include only traffic coming through specific data centers, or source for specific router types. Indicate the samplingSize to determine the number of timestamps to get data for. Enable sum to get aggregated data.

{
    "142.205.0.0/16": {
        "BORDER_FLOW_DFW3_ESP_BPS": {
            "1594148700000": 183500.8,
            "1594148820000": 10110020.267,
            "1594148880000": 3023394.133,
            "1594148940000": 11543868.4,
            "1594149000000": 5758845.867,
            "1594149060000": 11029211.467,
            "1594149120000": 11703461.067,
            "1594149180000": 4535091.2,
            "1594149480000": 183500.8,
            "1594151160000": 200977.067,
            "1594152000000": 113595.733
        },
        "ACCESS_FLOW_DFW3_ESP_BPS": {
            "1594148700000": 183500.8,
            "1594148820000": 10110020.267,
            "1594148880000": 3023394.133,
            "1594148940000": 11543868.4,
            "1594149000000": 5758845.867,
            "1594149060000": 11029211.467,
            "1594149120000": 11703461.067,
            "1594149180000": 4535091.2,
            "1594149480000": 183500.8,
            "1594151160000": 200977.067,
            "1594152000000": 113595.733
        },
        "aggregatedData": {
            "ACCESS_FLOW_DFW3_ESP_BPS": 1322132,
            "ACCESS_FLOW_DFW3_ESP_PPS": 23444.1223,
            "ACCESS_FLOW_DFW3_ICMP_BPS": 1223.22,
            "ACCESS_FLOW_DFW3_ICMP_PPS": 1223.344,
            "ACCESS_FLOW_DFW3_TCP_BPS": 123445.12,
            "ACCESS_FLOW_DFW3_TCP_PPS": 76655.23,
            "ACCESS_FLOW_DFW3_TOTAL_BPS": 1234,
            "ACCESS_FLOW_DFW3_TOTAL_PPS": 1323,
            "ACCESS_FLOW_DFW3_UDP_BPS": 1233,
            "ACCESS_FLOW_DFW3_UDP_PPS": 2132,
            "BORDER_FLOW_DFW3_ESP_BPS": 12233,
            "BORDER_FLOW_DFW3_ESP_PPS": 2133,
            "BORDER_FLOW_DFW3_ICMP_BPS": 1233,
            "BORDER_FLOW_DFW3_ICMP_PPS": 167888.34,
            "BORDER_FLOW_DFW3_TCP_BPS": 766554.23,
            "BORDER_FLOW_DFW3_TCP_PPS": 12345.788,
            "BORDER_FLOW_DFW3_TOTAL_BPS": 12344.77,
            "BORDER_FLOW_DFW3_TOTAL_PPS": 659878.22,
            "BORDER_FLOW_DFW3_UDP_BPS": 6555788,
            "BORDER_FLOW_DFW3_UDP_PPS": 76555.865
        }
    }
}

Data

This section provides you with the data model for the Prolexic Analytics API.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Metric

Encapsulates the target contract and time constraints for the specified metrics.

Download schema: MetricDataInput.json

Sample POST request:

{
    "contract": "venus",
    "start": 1322390037,
    "end": 1400385899,
    "samples": 100,
    "type": {
        "routed": [
            "bandwidthIn"
        ],
        "fbm": [
            {
                "metric": "bandwidth",
                "protocol": "total",
                "subnet": "1.1.1.0/24"
            },
            {
                "metric": "packets",
                "protocol": "tcp",
                "ip": "1.1.1.10"
            }
        ]
    }
}

Metric members

MetricType

Encapsulates information on the types of metrics available to the contract.

Download schema: MetricType.json

Sample GET response:

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Metric Types list acquired successfully",
    "data": {
        "routed": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "connect": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound packets, packets per second"
                }
            }
        },
        "mitigationPost": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "proxy": {
            "metrics": {
                "latency": {
                    "desc": "Average latency of request"
                },
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "bandwidthOut": {
                    "desc": "Customer outbound traffic, bits per second"
                },
                "connections": {
                    "desc": "Connections count"
                },
                "packetsOut": {
                    "desc": "Customer outbound traffic, packets per second"
                },
                "requests": {
                    "desc": "Requests count"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "mitigationPre": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "fbm": {
            "metrics": {
                "bandwidth": {
                    "desc": "Customer traffic bits per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                },
                "packets": {
                    "desc": "Customer traffic packets per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                }
            }
        }
    }
}

MetricType members

Attack

Contains details about an attack, including location, time, and type of attack.

Download schema: AttackReports.json

Sample GET response:

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Attack report acquired successfully",
    "data": [
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18594,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "SJC",
            "endTime": 1390261538,
            "eventBw": 500000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 1200,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        },
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18595,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "LON",
            "endTime": 1390261538,
            "eventBw": 90000000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 200000,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        }
    ]
}

Attack members

Event

Encapsulates the details of an event and the associated attack information.

Download schema: EventResponse.json

Sample GET response:

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully",
    "data": [
        {
            "service": "man",
            "eventType": "alert",
            "isOngoing": false,
            "eventStartTime": 1390975985,
            "eventTitle": "chkInt: Interface GigabitEthernet0/18 is down.",
            "severity": 80,
            "eventEndTime": 1393236546,
            "eventInfo": {
                "location": "mia1",
                "lastOccurred": 1393236546,
                "attackId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems"
            }
        },
        {
            "service": "Mitigation",
            "eventType": "attack",
            "isOngoing": true,
            "eventStartTime": 1392922838,
            "eventTitle": "[\"SYN Flood\"]",
            "severity": 100,
            "eventEndTime": 0,
            "eventInfo": {
                "eventTicketId": "70167",
                "attackType": "[\"SYN Flood\"]",
                "endTime": false,
                "attackEventId": "2707",
                "destinationIPs": "[178.132.240.114/32, 178.132.240.155/32, 178.132.240.203/32]",
                "startTime": 1392922838
            }
        }
    ]
}

Event members

TimeSeries

Contains attack and individual usage information for selected destination IP addresses or CIDR blocks in a three-level mapping object. An IP address or CIDR block keys appear at the top-level. The nested keys represent different report data facets. The lowest level shows keys for each data point’s individual epoch timestamp.

Download schema: TimeSeriesDataResponse.json

Sample GET response:

{
    "142.205.0.0/16": {
        "BORDER_FLOW_DFW3_ESP_BPS": {
            "1594148700000": 183500.8,
            "1594148820000": 10110020.267,
            "1594148880000": 3023394.133,
            "1594148940000": 11543868.4,
            "1594149000000": 5758845.867,
            "1594149060000": 11029211.467,
            "1594149120000": 11703461.067,
            "1594149180000": 4535091.2,
            "1594149480000": 183500.8,
            "1594151160000": 200977.067,
            "1594152000000": 113595.733
        },
        "ACCESS_FLOW_DFW3_ESP_BPS": {
            "1594148700000": 183500.8,
            "1594148820000": 10110020.267,
            "1594148880000": 3023394.133,
            "1594148940000": 11543868.4,
            "1594149000000": 5758845.867,
            "1594149060000": 11029211.467,
            "1594149120000": 11703461.067,
            "1594149180000": 4535091.2,
            "1594149480000": 183500.8,
            "1594151160000": 200977.067,
            "1594152000000": 113595.733
        },
        "aggregatedData": {
            "ACCESS_FLOW_DFW3_ESP_BPS": 1322132,
            "ACCESS_FLOW_DFW3_ESP_PPS": 23444.1223,
            "ACCESS_FLOW_DFW3_ICMP_BPS": 1223.22,
            "ACCESS_FLOW_DFW3_ICMP_PPS": 1223.344,
            "ACCESS_FLOW_DFW3_TCP_BPS": 123445.12,
            "ACCESS_FLOW_DFW3_TCP_PPS": 76655.23,
            "ACCESS_FLOW_DFW3_TOTAL_BPS": 1234,
            "ACCESS_FLOW_DFW3_TOTAL_PPS": 1323,
            "ACCESS_FLOW_DFW3_UDP_BPS": 1233,
            "ACCESS_FLOW_DFW3_UDP_PPS": 2132,
            "BORDER_FLOW_DFW3_ESP_BPS": 12233,
            "BORDER_FLOW_DFW3_ESP_PPS": 2133,
            "BORDER_FLOW_DFW3_ICMP_BPS": 1233,
            "BORDER_FLOW_DFW3_ICMP_PPS": 167888.34,
            "BORDER_FLOW_DFW3_TCP_BPS": 766554.23,
            "BORDER_FLOW_DFW3_TCP_PPS": 12345.788,
            "BORDER_FLOW_DFW3_TOTAL_BPS": 12344.77,
            "BORDER_FLOW_DFW3_TOTAL_PPS": 659878.22,
            "BORDER_FLOW_DFW3_UDP_BPS": 6555788,
            "BORDER_FLOW_DFW3_UDP_PPS": 76555.865
        }
    }
}

TimeSeries members

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

Responses from the API include status and statusMsg parameters indicating the success or failure of a request. For a failed request, the status boolean will be set to false and statusMsg will contain a string explaining the error condition, such as in the following example:

{
    "status": false,
    "statusMsg": "Description of failure"
}

For non–2xx HTTPS returned status codes, the error JSON below is returned as outlined. See HTTP Status Codes below for a list of error codes.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Reply Body:
{
    "type": "https://developer.akamai.com/api/luna/prolexic-analytics/overview.html#ratelimiting"
    "title": "Too many requests"
    "status" : 429,
    "detail": "additional non-http specific info where relevant"
}

HTTP status codes

This section lists the full range of response codes the API may generate.