Global Traffic Management Reporting API v1

Provides reports on GTM's real-time statistics like traffic, liveness, direct demand, load feedback, and latency.

Learn more:

Overview

The Traffic Management Reporting API provides read-only reports on GTM’s real time statistics. Each call allows you to view traffic, liveness, direct demand, load feedback, and latency on datacenters and properties.

Who should use this API

This API is for site administrators, project managers, technical support providers, and others who implement traffic management reporting for your organization. It assumes that you have a working knowledge of traffic management reporting and GTM.

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 Traffic Management Reporting, and set the access level to READ-ONLY.

Dual format responses

Operations for the API produces either JSON or CSV, depending on the value of the Accept header sent as part of the request.

Resources

The Traffic Management Reporting API allows you to view reports for GTM statistics.

The following provides a road map of all the conceptual objects you deal with when interacting with GTM reports, and provides pointers to where you can learn more.

  • Domain: A Traffic Management domain is a domain with one or more subdomains that share a number of attributes that you can only configure domain-wide. These attributes include use of load imbalance factor and the set of available data centers. Each Domain object is a representation of a complete GTM domain, such as example.akadns.net.

  • Property: Representation of GTM property, such as www, which in DNS terms is a subdomain of the domain. Combined with its domain, such as example.akadns.net, the fully qualified domain name www.example.akadns.net is used for load balancing.

  • Datacenter: A group of co-located servers that are load balanced as a unit.

  • Resource: An abstract entity that constrains the load on the properties that it governs. The goal of resources is to encapsulate the architecture and topology of the network in a data center. For example, each property normally has an associated resource that represents the capacity of the servers for that property. In addition, there might be a resource that constrains the aggregate bandwidth available to all properties in a data center.

Refer to the Global Traffic Management User Guide for additional information.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List domains GET /gtm-api/v1/reports/domain-list
Get a domain GET /gtm-api/v1/reports/domain-list/{domain}
Report directed demand for a property GET /gtm-api/v1/reports/demand/domains/{domain}/properties/{property}{?start,end}
Get a directed demand report window GET /gtm-api/v1/reports/demand/domains/{domain}/properties/{property}/window
List IP availability per property GET /gtm-api/v1/reports/ip-availability/domains/{domain}/properties/{property}{?start,end,ip,mostRecent,datacenterId}
Report latency per data center GET /gtm-api/v1/reports/latency/domains/{domain}/datacenters/{datacenterId}{?start,end,latency,loss}
Get a liveness test report window GET /gtm-api/v1/reports/liveness-tests/window
Report liveness per property GET /gtm-api/v1/reports/liveness-tests/domains/{domain}/properties/{property}{?date,agentIp,targetIp}
List liveness test errors GET /gtm-api/v1/reports/liveness-tests/error-code-descriptions
Get a liveness test error GET /gtm-api/v1/reports/liveness-tests/error-code-descriptions/{errorCode}
Get a load feedback report window GET /gtm-api/v1/reports/load-feedback/domains/{domain}/window
Report load feedback GET /gtm-api/v1/reports/load-feedback/domains/{domain}/resources/{resource}{?start,end}
Get a datacenter traffic report window GET /gtm-api/v1/reports/traffic/datacenters-window
Get a property traffic report window GET /gtm-api/v1/reports/traffic/properties-window
Report traffic per data center GET /gtm-api/v1/reports/traffic/domains/{domain}/datacenters/{datacenterId}{?start,end}
Report traffic per property GET /gtm-api/v1/reports/traffic/domains/{domain}/properties/{property}{?start,end}

List domains

This operation retrieves a list of domains, along with a URL templated link to obtain a domain summary of associated properties and datacenters for each.

GET /gtm-api/v1/reports/domain-list

Status 200 application/json

Download schema: domain-list.json

Response body:

{
    "domains": [
        "example.akadns.net",
        "more-examples.akadns.net"
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://localhost:9090/gtm-api/v1/reports/domain-list/"
        },
        {
            "rel": "domain",
            "href": "http://localhost:9090/gtm-api/v1/reports/domain-list/{domain}"
        }
    ]
}

Get a domain

This operation retrieves a list of property names, as well as Datacenter names and IDs for a given domain.

GET /gtm-api/v1/reports/domain-list/{domain}

Sample: /gtm-api/v1/reports/domain-list/example.akadns.net

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.

Status 200 application/json

Download schema: domain-summary.json

Response body:

{
    "name": "example.akadns.net",
    "properties": [
        "www",
        "db"
    ],
    "datacenters": [
        {
            "datacenterId": 3132,
            "datacenterNickname": "Winterfell"
        },
        {
            "datacenterId": 3133,
            "datacenterNickname": "Braavos"
        }
    ],
    "resources": [
        "cpu",
        "disk"
    ]
}

Report directed demand for a property

The requests generated by the client machines behind a client name-server represent demand. This API returns a collection of reports containing the provisioned demand percentage as opposed to actual demand percentage seen by GTM rounded off to nearest 5 min interval for each data center. This API returns no data for load feedback-based domains, as those domains do not have a configured per data center load.

GET /gtm-api/v1/reports/demand/domains/{domain}/properties/{property}{?start,end}

Sample: /gtm-api/v1/reports/demand/domains/example.akadns.net/properties/www?start=2016-05-23T01%3A56%3A13Z&end=2016-05-24T01%3A56%3A13Z

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
property String www Name of Traffic Management Property.
Required query parameters
end String 2016-05-24T01:56:13Z End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
start String 2016-05-23T01:56:13Z Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.

Status 200 application/json

Download schema: demand.json

Response body:

{
    "metadata": {
        "domain": "example.akadns.net",
        "property": "www",
        "start": "2017-02-14T14:51:27Z",
        "end": "2017-02-14T18:51:27Z",
        "uri": "http://localhost:9090/gtm-api/v1/reports/demand/domains/example.akadns.net/properties/cp140238?start=2017-02-14T14:51:27Z&end=2017-02-14T18:51:27Z"
    },
    "dataRows": [
        {
            "timestamp": "2017-02-14T14:51:27Z",
            "datacenters": [
                {
                    "percentProvisioned": 12.0,
                    "percentActual": 50.0,
                    "datacenterId": 3200,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4"
                },
                {
                    "percentProvisioned": 88.0,
                    "percentActual": 50.0,
                    "datacenterId": 3201,
                    "nickname": "Braavos",
                    "trafficTargetName": "Braavos - 1.2.3.5"
                }
            ]
        },
        {
            "timestamp": "2017-02-14T15:01:27Z",
            "datacenters": [
                {
                    "percentProvisioned": 12.0,
                    "percentActual": 50.0,
                    "datacenterId": 3200,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4"
                },
                {
                    "percentProvisioned": 88.0,
                    "percentActual": 50.0,
                    "datacenterId": 3201,
                    "nickname": "Braavos",
                    "trafficTargetName": "Braavos - 1.2.3.5"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://localhost:9090/gtm-api/v1/reports/demand/domains/example.akadns.net/properties/cp140238?start=2017-02-14T14:51:27Z&end=2017-02-14T18:51:27Z"
        }
    ]
}

Status 200 text/csv

Response body:

"domain","property","timestamp","datacenterId","datacenterNickname","trafficTargetName","percentProvisioned","percentActual"
"example.akadns.net","www","2017-02-25T14:34:10Z","3200","Winterfell","Winterfell - 1.2.3.4","12.0","50.0"
"example.akadns.net","www","2017-02-25T14:34:10Z","3201","Braavos","Braavos - 1.2.3.5","88.0","50.0"
"example.akadns.net","www","2017-02-25T14:44:10Z","3200","Winterfell","Winterfell - 1.2.3.4","12.0","50.0"
"example.akadns.net","www","2017-02-25T14:44:10Z","3201","Braavos","Braavos - 1.2.3.5","88.0","50.0"

Get a directed demand report window

Request the window of available data for a report. Returns a start and end date window. All requests for this related report need to include start and end dates that are within those endpoints, inclusive.

GET /gtm-api/v1/reports/demand/domains/{domain}/properties/{property}/window

Sample: /gtm-api/v1/reports/demand/domains/example.akadns.net/properties/www/window

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
property String www Name of Traffic Management Property.

Status 200 application/json

Download schema: report-window.json

Response body:

{
    "start": "2017-02-13T00:00:00Z",
    "end": "2018-02-23T15:05:00Z"
}

List IP availability per property

GTM combines scores (based on Liveness Tests) from all Web agents to calculate Server Scores and makes liveness decisions. A cutoff value is computed for each property from the median scores for all the servers in the property. Any property server with a score over the cutoff value is considered dead and it won’t be handed out. The request should have either start and end time or mostRecent, and not both.

In the response, handOut indicates whether the server was handed out and alive indicates whether GTM considered the server as alive or not.

GET /gtm-api/v1/reports/ip-availability/domains/{domain}/properties/{property}{?start,end,ip,mostRecent,datacenterId}

Sample: /gtm-api/v1/reports/ip-availability/domains/example.akadns.net/properties/www?start=2016-11-16T18%3A20%3A36Z&end=2016-11-17T18%3A20%3A36Z&ip=1.2.3.4&mostRecent=true&datacenterId=3132

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
property String www Name of Traffic Management property.
Optional query parameters
datacenterId Integer 3132 Data center ID.
end String 2016-11-17T18:20:36Z End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
ip String 1.2.3.4 IP address of the server.
mostRecent Boolean true Most recent update.
start String 2016-11-16T18:20:36Z Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.

Status 200 application/json

Download schema: ip-status.json

Response body:

{
    "metadata": {
        "domain": "example.akadns.net",
        "property": "www",
        "uri": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/ip-availability/domains/example.akadns.net/properties/www"
    },
    "dataRows": [
        {
            "timestamp": "2017-02-23T21:42:35Z",
            "cutOff": 112.5,
            "datacenters": [
                {
                    "datacenterId": 3132,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4",
                    "IPs": [
                        {
                            "ip": "1.2.3.4",
                            "score": 75.0,
                            "handedOut": true,
                            "alive": true
                        }
                    ]
                },
                {
                    "datacenterId": 3133,
                    "nickname": "Braavos",
                    "trafficTargetName": "Braavos - 1.2.3.5",
                    "IPs": [
                        {
                            "ip": "1.2.3.5",
                            "score": 85.0,
                            "handedOut": true,
                            "alive": true
                        }
                    ]
                }
            ]
        },
        {
            "timestamp": "2017-03-23T21:42:35Z",
            "cutOff": 112.5,
            "datacenters": [
                {
                    "datacenterId": 3132,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4",
                    "IPs": [
                        {
                            "ip": "1.2.3.4",
                            "score": 115.0,
                            "handedOut": false,
                            "alive": false
                        }
                    ]
                },
                {
                    "datacenterId": 3133,
                    "nickname": "Braavos",
                    "trafficTargetName": "Braavos - 1.2.3.5",
                    "IPs": [
                        {
                            "ip": "1.2.3.5",
                            "score": 75.0,
                            "handedOut": true,
                            "alive": true
                        }
                    ]
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/ip-availability/domains/example.akadns.net/properties/www"
        }
    ]
}

Status 200 text/csv

Response body:

"timestamp","domain","property","datacenterId","datacenterNickname","ip","score","cutOff","handOut","alive"
"2017-02-23T21:42:35Z","example.akadns.net","www","3200","Winterfell","Winterfell - 1.2.3.4","1.2.3.4","75.0","112.5","true","true"
"2017-02-23T21:42:35Z","example.akadns.net","www","3133","Braavos","Braavos - 1.2.3.5","1.2.3.5","85.0","112.5","true","true"
"2017-03-23T21:42:35Z","example.akadns.net","www","3200","Winterfell","Winterfell - 1.2.3.4","1.2.3.4","115.0","112.5","false","false"
"2017-03-28T21:42:35Z","example.akadns.net","www","3133","Braavos","Braavos - 1.2.3.5","1.2.3.5","75.0","112.5","true","true"

Report latency per data center

This operation returns a collection of reports representing latency and loss of ping data as reported by network agents in each Data Center for a property. Latency and Loss parameters follow bucket ranges schema, for example bucket ranges delimited by a pipe: |.

Ping Loss ranges from 0% to 100%. So a schema of 5|10|15|20 would represent grouping of data from 0% to 5%, 5% to 10%, 10% to 15%, 15% to 20%, and 20% to 100% bucket ranges. The end of one bucket would be the beginning of the next bucket. Similarly 0|5|80 would represent 0%, 0% to 5%, 5% to 100%, and 80% to 100% bucket ranges. A trailing pipe at the end of a bucket indicates that there is no greater than the max bucket, that is, in the above example if loss schema was 0|5|80| then it would mean 0%, 0% to 5%, and 5% to 80%.

Latency is measured in milliseconds. Each bucket ranges from 0 ms to 1000 ms. So, a schema of 5|10|300|1000 would mean 0ms to 5ms, 5ms to 10ms, 10ms to 300ms, 300ms to 1000ms, and > 1000ms.

GET /gtm-api/v1/reports/latency/domains/{domain}/datacenters/{datacenterId}{?start,end,latency,loss}

Sample: /gtm-api/v1/reports/latency/domains/example.akadns.net/datacenters/3200?start=2016-05-23T01%3A56%3A13Z&end=2016-05-24T01%3A56%3A13Z&latency=0%7C100%7C200%7C1000&loss=0%7C10%7C20%7C100

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of the Traffic Management domain.
datacenterId Integer 3200 ID of the data center.
Required query parameters
end String 2016-05-24T01:56:13Z End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
start String 2016-05-23T01:56:13Z Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
Optional query parameters
latency String 0|100|200|1000 Latency Bucket Schema.
loss String 0|10|20|100 Loss Bucket Schema.

Status 200 application/json

Download schema: latency.json

Response body:

{
    "metadata": {
        "loss": "0|100",
        "domain": "example.akadns.net",
        "latency": "0|1000",
        "datacenterId": 3200,
        "datacenterNickname": "Winterfell",
        "start": "2017-02-14T17:11:26Z",
        "end": "2017-02-14T18:11:26Z",
        "uri": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/latency/domains/example.akadns.net/datacenters/14762?start=2017-02-14T17:11:26Z&end=2017-02-14T18:11:26Z&latency=0%7C1000&loss=0%7C100"
    },
    "dataRows": [
        {
            "latency": [
                0,
                100,
                0
            ],
            "loss": [
                100,
                0,
                0
            ],
            "timestamp": "2017-02-14T17:11:26Z"
        },
        {
            "latency": [
                0,
                100,
                0
            ],
            "loss": [
                100,
                0,
                0
            ],
            "timestamp": "2017-02-14T17:21:30Z"
        },
        {
            "latency": [
                0,
                100,
                0
            ],
            "loss": [
                100,
                0,
                0
            ],
            "timestamp": "2017-02-14T17:31:31Z"
        },
        {
            "latency": [
                0,
                100,
                0
            ],
            "loss": [
                100,
                0,
                0
            ],
            "timestamp": "2017-02-14T17:41:27Z"
        },
        {
            "latency": [
                0,
                100,
                0
            ],
            "loss": [
                100,
                0,
                0
            ],
            "timestamp": "2017-02-14T17:51:30Z"
        },
        {
            "latency": [
                0,
                100,
                0
            ],
            "loss": [
                100,
                0,
                0
            ],
            "timestamp": "2017-02-14T18:01:27Z"
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/latency/domains/example.akadns.net/datacenters/14762?start=2017-02-14T17:11:26Z&end=2017-02-14T18:11:26Z&latency=0%7C1000&loss=0%7C100"
        }
    ]
}

Status 200 text/csv

Response body:

"domain","datacenterId","datacenterNickname","timestamp","latency","loss"
"example.akadns.net","3200","Winterfell","2017-02-25T14:24:07Z","[0, 100, 0]","[97, 3, 0]"
"example.akadns.net","3200","Winterfell","2017-02-25T14:34:10Z","[0, 100, 0]","[97, 3, 0]"

Get a liveness test report window

Request the window of available data for a report. Returns a start and end date window. All requests for this related report need to include start and end dates that are within those endpoints, inclusive.

GET /gtm-api/v1/reports/liveness-tests/window

Status 200 application/json

Download schema: report-window.json

Response body:

{
    "start": "2017-02-13T00:00:00Z",
    "end": "2018-02-23T15:05:00Z"
}

Report liveness per property

This operation returns a collection of reports containing logs of individual liveness tests which have failed. Liveness Tests are run periodically by Web Agents installed in customer data centers. Liveness scores are used by GTM to decide whether a data center is alive or not.

Liveness tests which fail in succession, for example tests that run from the same testing agent to the same origin server, which fail with the same error code, are grouped together and represented with a duration. This duration value is in seconds and can sustain for up to 86400 seconds, one day. If it crosses that boundary, GTM logs it as a new failure at the beginning of the next day (00:00 UTC), with the duration reset to that point.

GET /gtm-api/v1/reports/liveness-tests/domains/{domain}/properties/{property}{?date,agentIp,targetIp}

Sample: /gtm-api/v1/reports/liveness-tests/domains/example.akadns.net/properties/www?date=2015-08-31&agentIp=209.170.75.251&targetIp=192.0.2.2

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
property String www Name of Traffic Management property.
Required query parameters
date String 2015-08-31 Date of report, in ISO 8601 format of YYYY-MM-DD.
Optional query parameters
agentIp String 209.170.75.251 Filter results by Agent IP.
targetIp String 192.0.2.2 Filter results by Target IP.

Status 200 application/json

Download schema: liveness-tests.json

Response body:

{
    "metadata": {
        "date": "2016-11-23",
        "domain": "example.akadns.net",
        "property": "www",
        "uri": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/liveness-tests/domains/example.akadns.net/properties/www?date=2016-11-23"
    },
    "dataRows": [
        {
            "timestamp": "2016-11-23T00:13:23Z",
            "datacenters": [
                {
                    "datacenterId": 3201,
                    "agentIp": "204.1.136.239",
                    "testName": "Our defences",
                    "errorCode": 3101,
                    "duration": 0,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4",
                    "targetIp": "1.2.3.4"
                }
            ]
        },
        {
            "timestamp": "2016-11-23T00:15:13Z",
            "datacenters": [
                {
                    "datacenterId": 3202,
                    "agentIp": "204.1.136.239",
                    "testName": "Our defences",
                    "errorCode": 3101,
                    "duration": 0,
                    "nickname": "Braavos",
                    "trafficTargetName": "Braavos - 1.2.3.5",
                    "targetIp": "1.2.3.5"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/liveness-tests/domains/example.akadns.net/properties/www?date=2016-11-23"
        }
    ]
}

Status 200 text/csv

Response body:

"domain","property","timestamp","datacenterId","datacenterNickname","trafficTargetName","targetIp","agentIp","testName","duration","errorCode"
"example.akadns.net","www","2016-12-04T01:57:21Z","3200","Winterfell","Winterfell - 1.2.3.4","1.2.3.4","80.67.75.14","Our defences","3110"
"example.akadns.net","www","2016-12-04T01:57:53Z","3201","Braavos","1.2.3.5","80.67.75.14","Our defences","3100"
"example.akadns.net","www","2016-12-04T01:59:05Z","3200","Winterfell","Winterfell - 1.2.3.4","1.2.3.4","69.31.121.20","Our defences","3101"
"example.akadns.net","www","2016-12-04T01:59:46Z","3201","Braavos","Braavos - 1.2.3.5","1.2.3.5","65.124.174.194","Our defences","3101"

List liveness test errors

This operation lists all the possible liveness test error codes, as displayed on the Liveness Test Failures report, and a description of each error.

GET /gtm-api/v1/reports/liveness-tests/error-code-descriptions

Status 200 application/json

Response body:

{
    "items": [
        {
            "errorCode": 3082,
            "errorDescription": "Attempting to link in too many shared libraries"
        },
        {
            "errorCode": 3081,
            "errorDescription": ".lib section in a.out corrupted"
        }
    ]
}

Status 200 text/csv

Response body:

"errorCode ","errorDescription"
"3082","Attempting to link in too many shared libraries"
"3081",".lib section in a.out corrupted"

Get a liveness test error

This operation returns an error description for the given liveness test error ID.

GET /gtm-api/v1/reports/liveness-tests/error-code-descriptions/{errorCode}

Sample: /gtm-api/v1/reports/liveness-tests/error-code-descriptions/2200

Parameter Type Sample Description
URL path parameters
errorCode Number 2200 Error identification number.

Status 200 application/json

Response body:

{
    "items": [
        {
            "errorCode": 3082,
            "errorDescription": "Attempting to link in too many shared libraries"
        }
    ]
}

Status 200 text/csv

Response body:

"errorCode ","errorDescription"
"3082","Attempting to link in too many shared libraries"

Get a load feedback report window

Request the window of available data for a report. Returns a start and end date window. All requests for this related report need to include start and end dates that are within those endpoints, inclusive.

GET /gtm-api/v1/reports/load-feedback/domains/{domain}/window

Sample: /gtm-api/v1/reports/load-feedback/domains/example.akadns.net/window

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.

Status 200 application/json

Download schema: report-window.json

Response body:

{
    "start": "2017-02-13T00:00:00Z",
    "end": "2018-02-23T15:05:00Z"
}

Report load feedback

This report shows the historical values of a given Resource across all data centers and the given time period. A resource is anything that can constrain the load sent to a data center. Examples of typical resources include bandwidth, CPU load average, database queries per second, or disk operations per second.

GET /gtm-api/v1/reports/load-feedback/domains/{domain}/resources/{resource}{?start,end}

Sample: /gtm-api/v1/reports/load-feedback/domains/example.akadns.net/resources/cpu?start=2016-05-23T01%3A56%3A13Z&end=2016-05-24T01%3A56%3A13Z

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
resource String cpu Name of the resource.
Required query parameters
end String 2016-05-24T01:56:13Z End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
start String 2016-05-23T01:56:13Z Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.

Status 200 application/json

Download schema: load-feedback.json

Response body:

{
    "metadata": {
        "resource": "cpu",
        "domain": "example.akadns.net",
        "start": "2017-02-14T01:32:52Z",
        "end": "2017-02-14T01:40:52Z",
        "uri": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/load-feedback/domains/example.akadns.net/resources/cpu?start=2017-02-14T01:32:52Z&end=2017-02-14T01:40:52Z"
    },
    "dataRows": [
        {
            "timestamp": "2017-02-14T01:32:52Z",
            "datacenters": [
                {
                    "currentLoad": 20,
                    "targetLoad": 30,
                    "maximumLoad": 40,
                    "datacenterId": 3135,
                    "nickname": "Winterfell"
                },
                {
                    "currentLoad": 30,
                    "targetLoad": 40,
                    "maximumLoad": 40,
                    "datacenterId": 3139,
                    "nickname": "Bravoos"
                },
                {
                    "currentLoad": 10,
                    "targetLoad": 10,
                    "maximumLoad": 15,
                    "datacenterId": 3140,
                    "nickname": "King's Landing"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/load-feedback/domains/example.akadns.net/resources/cpu?start=2017-02-14T01:32:52Z&end=2017-02-14T01:40:52Z"
        }
    ]
}

Status 200 text/csv

Response body:

"domain","resource","timestamp","datacenterId","datacenterNickname","currentLoad","targetLoad","maximumLoad"
"example.akadns.net","cpu","2017-02-25T03:46:51Z","3200","Winterfell","20","30","40"
"example.akadns.net","cpu","2017-02-25T03:46:51Z","3201","Braavos","30","40","40"
"example.akadns.net","cpu","2017-02-25T04:46:51Z","3200","Winterfell","10","30","40"
"example.akadns.net","cpu","2017-02-25T04:46:51Z","3201","Braavos","10","40","40"

Get a datacenter traffic report window

Request the window of available data for a report. Returns a start and end date window. All requests for this related report need to include start and end dates that are within those endpoints, inclusive.

GET /gtm-api/v1/reports/traffic/datacenters-window

Status 200 application/json

Download schema: report-window.json

Response body:

{
    "start": "2017-02-13T00:00:00Z",
    "end": "2018-02-23T15:05:00Z"
}

Get a property traffic report window

Request the window of available data for a report. Returns a start and end date window. All requests for this related report need to include start and end dates that are within those endpoints, inclusive.

GET /gtm-api/v1/reports/traffic/properties-window

Status 200 application/json

Download schema: report-window.json

Response body:

{
    "start": "2017-02-13T00:00:00Z",
    "end": "2018-02-23T15:05:00Z"
}

Report traffic per data center

This report shows, for a given domain and data center, the DNS requests received in each five-minute period. Requests are broken down by property.

GET /gtm-api/v1/reports/traffic/domains/{domain}/datacenters/{datacenterId}{?start,end}

Sample: /gtm-api/v1/reports/traffic/domains/example.akadns.net/datacenters/3200?start=2016-05-23T01%3A56%3A13Z&end=2016-05-24T01%3A56%3A13Z

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
datacenterId Integer 3200 Data center ID.
Required query parameters
end String 2016-05-24T01:56:13Z End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
start String 2016-05-23T01:56:13Z Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.

Status 200 application/json

Download schema: traffic-datacenter.json

Response body:

{
    "metadata": {
        "domain": "example.akadns.net",
        "datacenterId": 3200,
        "datacenterNickname": "Winterfell",
        "start": "2016-11-23T00:00:00Z",
        "end": "2016-11-23T00:10:00Z",
        "interval": "FIVE_MINUTE",
        "uri": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/traffic/domains/example.akadns.net/datacenters?start=2016-11-23T00:00:00Z&end=2016-11-23T00:10:00Z"
    },
    "dataRows": [
        {
            "timestamp": "2016-11-23T00:00:00Z",
            "properties": [
                {
                    "name": "www",
                    "requests": 45,
                    "status": "1"
                }
            ]
        },
        {
            "timestamp": "2016-11-23T00:05:00Z",
            "properties": [
                {
                    "name": "www",
                    "requests": 45,
                    "status": "1"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/traffic/domains/example.akadns.net/datacenters?start=2016-11-23T00:00:00Z&2016-11-23T00:10:00Z"
        }
    ]
}

Status 200 text/csv

Response body:

"timestamp","domain","property","datacenterId","datacenterNickname","requests","status"
"2017-03-01T20:30:00Z","example.akadns.net","www","3132","Winterfell","39","1"
"2017-03-01T20:35:00Z","example.akadns.net","www","3132","Winterfell","266","1"

Report traffic per property

This report shows, for a given domain and property, the DNS requests received in each five-minute period. Requests are broken down by data center.

GET /gtm-api/v1/reports/traffic/domains/{domain}/properties/{property}{?start,end}

Sample: /gtm-api/v1/reports/traffic/domains/example.akadns.net/properties/www?start=2016-05-23T01%3A56%3A13Z&end=2016-05-24T01%3A56%3A13Z

Parameter Type Sample Description
URL path parameters
domain String example.akadns.net Name of Traffic Management domain.
property String www Name of Traffic Management property.
Required query parameters
end String 2016-05-24T01:56:13Z End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
start String 2016-05-23T01:56:13Z Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.

Status 200 application/json

Download schema: traffic-property.json

Response body:

{
    "metadata": {
        "domain": "example.akadns.net",
        "property": "www",
        "start": "2016-11-24T01:40:00Z",
        "end": "2016-11-24T01:50:00Z",
        "interval": "FIVE_MINUTE",
        "uri": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/traffic/domains/example.akadns.net/properties/www?start=2016-11-23T00:00:00Z&2016-11-24T01:50:00Z"
    },
    "dataRows": [
        {
            "timestamp": "2016-11-24T01:40:00Z",
            "datacenters": [
                {
                    "datacenterId": 3130,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4",
                    "requests": 34,
                    "status": "1"
                }
            ]
        },
        {
            "timestamp": "2016-11-24T01:45:00Z",
            "datacenters": [
                {
                    "datacenterId": 3130,
                    "nickname": "Winterfell",
                    "trafficTargetName": "Winterfell - 1.2.3.4",
                    "requests": 45,
                    "status": "1"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/gtm-api/v1/reports/traffic/domains/example.akadns.net/properties/www?start=2016-11-23T00:00:00Z&2016-11-24T01:50:00Z"
        }
    ]
}

Status 200 text/csv

Response body:

"timestamp","domain","property","datacenterId","datacenterNickname","trafficTargetName","requests","status"
"2017-03-01T20:30:00Z","example.akadns.net","www","3132","Winterfell","Winterfell - 1.2.3.4","39","1"
"2017-03-01T20:35:00Z","example.akadns.net","www","3133","Braavos","Braavos - 1.2.3.5","266","1"

Data

This section provides you with the data model for the Traffic Management Reporting API.

Download the JSON schemas for this API.

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

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.

DataCenter

This object provides reports for data centers, broken down by timestamp, datacenterId, or property, at five-minute granularity.

Download schema: inner_datacenter.json

Sample GET response:

{
    "datacenters": [
        {
            "datacenterId": 3202,
            "agentIp": "204.1.136.239",
            "testName": "Our defences",
            "errorCode": 3101,
            "duration": 0,
            "nickname": "Krak\u00f3w office",
            "targetIp": "1.2.3.5"
        }
    ]
}

DataCenter members

Member Type Required Description
DataCenter: This object provides reports for data centers, broken down by timestamp, datacenterId, or property, at five-minute granularity.
agentIp String ○ IP address of the server monitor agent that encountered the error.
currentLoad Number ○ Current load for a resource.
datacenterId Integer ✓ Unique identifier for each data center.
duration Integer ○ Duration of the error in seconds.
errorCode Integer ○ Integer ID of the Error.
IPs DataCenter.IPs[] ✓ Container for each server IP in the data center.
maximumLoad Number ○ Maximum load for a resource.
nickname String ✓ Nickname of the data center.
percentActual Number ○ Percentage of actual demand for a resource.
percentProvisioned Number ○ Percentage of provisioned demand for a resource.
requests Integer ○ Number of DNS requests.
targetIp String ○ IP address of the target server.
targetLoad Number ○ Target load for a resource.
testName String ○ Name of liveness test.
DataCenter.IPs[]: Container for each server IP in the data center.
alive Boolean ✓ True when the server is considered as alive.
handedOut Boolean ✓ True when the server has been handed out.
ip String ✓ IP address of the server.
score Number ✓ Server score based on liveness tests.

Metadata

This object contains the API request data for URL and query parameters.

Download schema: inner_metadata.json

Sample GET response:

{
    "metadata": {
        "start": "2015-08-31T15:05:00Z",
        "end": "2015-08-31T15:10:00Z",
        "domain": "example.akadns.net",
        "datacenter": "3200",
        "uri": "http://localhost:9090/gtm-api/v1/reports/traffic/domains/example.akadns.net/datacenters/3200?start=2015-08-31T15:05:00Z&end=2015-08-31T15:10:00Z"
    }
}

Metadata members

Member Type Required Description
Metadata: This object contains the API request data for URL and query parameters.
agentIp String ○ IP address of the server monitor agent that encountered the error.
datacenterId Integer ○ Integer ID of the data center.
datacenterNickname String ○ Nickname of the data center.
date String ○ Date of report, in ISO 8601 format of YYYY-MM-DD.
domain String ✓ Name of the Traffic Management domain.
end String ✓ End date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
interval Enumeration ○ Value of time for report granularity. The only currently available value is FIVE_MINUTE.
ip String ○ IP Address of the server.
latency String ○ Latency in milliseconds, formatted to supplied bucket schema.
loss String ○ Percentage loss, formatted to supplied bucket schema.
mostRecent Boolean ○ Fetch the most recent update.
property String ✓ Name of Traffic Management property.
region Integer ○ Region or data center ID.
resource String ○ Name of the resource.
start String ✓ Start date of report, in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time.
targetIp String ○ IP address of the test target.
uri String ✓ URL of the API call.

Error

This object provides details for error codes and their descriptions.

Download schema: inner_error.json

Sample GET response:

{
    "items": [
        {
            "errorCode": 3082,
            "errorDescription": "Attempting to link in too many shared libraries"
        }
    ]
}

Error members

Member Type Required Description
Error: This object provides details for error codes and their descriptions.
errorCode Integer ✓ Integer ID of the error.
errorDescription String ✓ Error message when requests for reports fails.

Errors

This section tells you what you need to know about the GTM Reporting API’s error response format, and details the range of HTTP status codes the API produces.

Error responses

EdgeGrid responds with HTTP problem error objects that provide details useful for debugging. For example:

{
  "type" : "https://problems.luna.akamaiapis.net/-/pep-authn/request-error",
  "title" : "Bad request",
  "status" : 400,
  "detail" : "Authorization header missing",
  "instance" : "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/data-dns/v1/traffic/xxx.xxxxxxxxx.xxx?20150411&00:00&20150414&23:59&EST&false",
  "method" : "GET",
  "serverIp" : "nnn.nnn.nnn.nnn",
  "clientIp" : "nnn.nnn.nnn.nnn",
  "requestId" : "372819f9",
  "requestTime" : "2015-04-16T14:56:52Z"
}

HTTP status codes

The API produces this set of HTTP status codes for both success and failure scenarios:

Code Description
200 Request OK
400 Bad Request
401 Unauthorized Request
403 Forbidden
404 Resource not found
405 Method not allowed