- Overview
- Resources
- API summary
- Get a domain list
- Get a domain summary
- Report directed demand for a property
- List IP availability per property
- Report latency per data center
- Report liveness per property
- List liveness test errors
- Get a liveness test error
- Report load feedback
- Report traffic per data center
- Report traffic per property
- Data
- Errors
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:
Download this API’s RAML and JSON schema descriptors.
Overview
The Global 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
Before using the Beta API for the first time:
During the Beta period, contact your Akamai representative to enable the API for your account.
Review Get Started for API tools that Akamai provides.
Review Authorize Your Client to create your Akamai API access credentials and authorizations, making sure you enable read access for the Global Traffic Management Reporting API. As detailed in The API Identity Model, you then access the API using custom hostnames that looks like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.If you need help, provide feedback with the Akamai developer community, or else contact your Akamai representative for support.
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 can only be configured domain-wide. These attributes include use of load imbalance factor, the set of available data centers, etc. 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 asexample.akadns.net), the fully qualified domain namewww.example.akadns.netis 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.
Please refer to the Global Traffic Management User Guide for additional information.
API summary
Download the RAML descriptors for this API.
| Operation | Method | Endpoint |
|---|---|---|
| Get a Domain List | GET | /gtm-api/ |
| Get a Domain Summary | GET | /gtm-api/ |
| Report Directed Demand for a Property | GET | /gtm-api/ |
| List IP Availability per Property | GET | /gtm-api/ |
| Report Latency per Data Center | GET | /gtm-api/ |
| Report Liveness per Property | GET | /gtm-api/ |
| List Liveness Test Errors | GET | /gtm-api/ |
| Get a Liveness Test Error | GET | /gtm-api/ |
| Report Load Feedback | GET | /gtm-api/ |
| Report Traffic per Data Center | GET | /gtm-api/ |
| Report Traffic per Property | GET | /gtm-api/ |
Get a domain list
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/
Status 200
application/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 summary
This operation retrieves a list of property names, as well as Datacenter names and IDs for a given domain.
GET /gtm-api/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
domain |
String | example.akadns.net |
Name of Traffic Management domain. |
Status 200
application/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 vs 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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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"
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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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 (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,
i.e. 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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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]"
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 (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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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/
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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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"
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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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"
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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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/
Sample: /gtm-api/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL 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
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.
The data schema tables below list membership requirements as follows:
| ✓ | Member is required to be present, regardless of whether 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 |
|---|---|---|---|
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. |
✓ | 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 |
|---|---|---|---|
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 |
|---|---|---|---|
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 the following 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 |
Last modified: 6/2/2017