Diagnostic Tools API v1

The original version of Diagnostic Tools explores problems in DNS host-name mapping and network routing.

Learn more:


Overview

The Diagnostic Tools API offers programmatic access to a subset of Akamai’s diagnostic toolset available in Luna Control Center. With these tools you can self-diagnose and solve many common problems Akamai customers experience.

  • Locations: Returns a list of active Akamai server locations, from which you can run diagnostic tools.
  • dig: Run dig from the Akamai network to get a view of DNS information not local to you.
  • mtr: Run mtr from the Akamai network to a hostname.
  • Akamai Translator: Retrieve information about an Akamaized URL.
  • Error Translator: Translate an Akamai error code or reference number.
  • IP Geolocator: Retrieve the location details for an IP address.
  • Verify CDN IP: Verify whether or not the IP provided is on this CDN.

NOTE: This is the legacy API version 1 of the Diagnostic Tools API. See version 2 for a fuller set of utilities.

Who should use this API

If you want to programmatically problem-solve issues with your Akamai-enabled property, you should consider using this API.

Getting started

  • Review Get Started for tools that Akamai provides for all its APIs.

  • Visit the akamai-open repository to download reference EdgeGrid clients and sample code.

  • Review Authorize Your Client to create your access credentials and authorizations, making sure you enable read access for the Diagnostic Tools API.

  • To make API calls to Diagnostic Tools, you may need to add items to your contract. Please contact your Akamai account team for assistance.

  • Get help from the Akamai developer community and provide feedback. You can also contact your Akamai representative for support. We want to hear from you!

Rate limiting

The API applies a dynamic system of rate limiting for each API endpoint based on the total number of requests allowed within a given burst. Clients may rely on contextual HTTP response headers:

  • X-RateLimit-Limit: the total number of requests allowed.
  • X-RateLimit-Remaining: how many requests remain.

For each endpoint’s limit, there is a corresponding interval at which the number of remaining requests increments by one until it once again reaches the limit. The table below shows the total number of requests allowed for each endpoint and the interval (in seconds) at which remaining requests replenish. For example, with a request limit of 90 and a replenishment interval of 960 seconds, you can send a single burst of 90 requests, but then must wait 16 minutes to make each additional request, so that the effective daily limit is 180.

Interface Endpoint Request
Limit
Replenishment
Interval
Akamai Translator /diagnostic-tools/v1/akamaitranslator 90 960
dig /diagnostic-tools/v1/dig 90 960
Error Translator /diagnostic-tools/v1/errortranslator 90 960
IP Geolocator /diagnostic-tools/v1/ipgeolocator 250 300
Locations /diagnostic-tools/v1/locations 180 480
mtr /diagnostic-tools/v1/mtr 90 960
Verify CDN IP /diagnostic-tools/v1/verifycdnip 90 960

Resources

This section provides details on the Diagnostic Tools API’s available set of URL operations.

API summary

Operation Method Endpoint
List Locations GET /diagnostic-tools/v1/locations
Run dig GET /diagnostic-tools/v1/dig{?hostname,queryType,location,sourceIp}
Run mtr GET /diagnostic-tools/v1/mtr{?destinationDomain,location,sourceIp}
Translate Hostname GET /diagnostic-tools/v1/akamaitranslator{?hostname}
Translate Error Code GET /diagnostic-tools/v1/errortranslator{?errorCode}
Get IP Geolocation GET /diagnostic-tools/v1/ipgeolocator{?ip}
Verify if an IP is Within the CDN GET /diagnostic-tools/v1/verifycdnip{?ip}

List locations

This operation lists active Akamai server locations from which you can run diagnostic tools. The dig and mtr tools use elements from this list. The response is a locationsContainer object with a list of locations or an errorString if the request fails.

GET /diagnostic-tools/v1/locations

Status 200 application/json

Response:

{
    "locations": [
        "city1, country",
        "city2, country"
    ],
    "errorString": null
}

Run dig

Run dig for a given hostname from an Akamai location. Dig looks up IP addresses from hostnames on the nameserver running on the Akamai edge server. It can help you determine which IP address the Akamai edge server uses to resolve your hostname. The response is a digContainer with dig output or an errorString if the request fails.

GET /diagnostic-tools/v1/dig{?hostname,queryType,location,sourceIp}

Example: /diagnostic-tools/v1/dig?hostname=developer.akamai.com&queryType=A&location=Sydney%2C+Australia&sourceIp=NN.NN.NN.NN

Parameter Type Sample Description
Required
hostname String developer.akamai.com the domain name you want to get information about.
location String Sydney, Australia Location of Akamai server from which you want to run dig. You can find servers using GET /diagnostic-tools/v1/locations.
queryType Enumeration A query type for the dig; valid types are:. Possible values: AAAA, A, CNAME, MX, PTR, SOA.
Optional
sourceIp String NN.NN.NN.NN CDN server IP to run DIG from.

Status 200 application/json

Response:

{
    "dig": {
        "hostname": "www.example.com.",
        "queryType": "A",
        "answerSection": [
            {
                "domain": "www.example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "A",
                "ttl": "5",
                "value": "NN.NN.NN.NN"
            }
        ],
        "authoritySection": [
            {
                "domain": "example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "NS",
                "ttl": "86399",
                "value": "a.example.net."
            },
            {
                "domain": "example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "NS",
                "ttl": "86399",
                "value": "b.example.net."
            }
        ],
        "result": "\n; <<>> DiG 9.8.1-P1 <<>> www.example.com -t A\n...",
        "errorString": null
    }
}

  1. Retrieve the locations container.

  2. Select a location from the list.

  3. URL-encode the location.

  4. Construct and submit the dig request.

Run mtr

Run mtr for a given hostname from an Akamai location. Network Connectivity Tester (mtr) combines the functionality of the traceroute and ping programs in a single network diagnostic tool. It investigates the network connection between the host on which mtr runs and the destinationDomain. The results of mtr show you how many network hops a packet takes from the Akamai server to the host and how long each hop takes. The statistics can show you where network delays are being introduced in the path. The response is a mtrContainer with mtr output or an errorString if the request fails.

GET /diagnostic-tools/v1/mtr{?destinationDomain,location,sourceIp}

Example: /diagnostic-tools/v1/mtr?destinationDomain=developer.akamai.com&location=Sydney%2C+Australia&sourceIp=NN.NN.NN.NN

Parameter Type Sample Description
Required
destinationDomain String developer.akamai.com The domain name you want to get information about.
location String Sydney, Australia Location of Akamai Server you want to run dig from. You can find servers using GET /diagnostic-tools/v1/locations. Either this parameter or sourceIp is required.
Optional
sourceIp String NN.NN.NN.NN CDN server IP to run MTR from. Either this parameter or location is required.

Status 200 application/json

Response:

{
    "mtr": {
        "source": null,
        "destination": "www.example.com",
        "host": "aNNN-NNN-NNN-NN.deploy.example.net",
        "packetLoss": "0.0",
        "avgLatency": "0.3",
        "analysis": "",
        "errorString": null,
        "hops": [
            {
                "num": "1.|-",
                "host": "NNNN:NNN:N:NNN::N",
                "loss": "0.0",
                "sent": "10",
                "last": "0.2",
                "avg": "0.3",
                "best": "0.2",
                "worst": "0.8",
                "stDev": "0.0"
            },
            {
                "num": "2.|-",
                "host": "XXN-NNN.XXXNN.example.net",
                "loss": "0.0",
                "sent": "10",
                "last": "0.3",
                "avg": "4.6",
                "best": "0.3",
                "worst": "33.9",
                "stDev": "10.7"
            },
            {
                "num": "3.|-",
                "host": "XX-N-N-N.XXXNN.example.ne",
                "loss": "0.0",
                "sent": "10",
                "last": "0.6",
                "avg": "0.4",
                "best": "0.3",
                "worst": "0.6",
                "stDev": "0.0"
            }
        ]
    }
}

  1. Retrieve the locations container.

  2. Select a location from the list.

  3. URL-encode the location.

  4. Construct and submit the mtr request.

Translate hostname

Translates an Akamaized URL (ARL) into typecode, origin server, CP code, serial number, and TTL. The response is an ARLContainer with details on the ARL or an errorString if the request fails.

GET /diagnostic-tools/v1/akamaitranslator{?hostname}

Example: /diagnostic-tools/v1/akamaitranslator?hostname=host.example.com

Parameter Type Sample Description
Required
hostname String host.example.com Hostname for which to retrieve ARL information.

Status 200 application/json

Response:

{
    "arl": {
        "typeCode": "Object changes when ARL changes",
        "originServer": "origin.example.com",
        "cpCode": "12345",
        "serialNumber": "54321",
        "ttl": "Infinite",
        "pragma": null,
        "cacheControl": null,
        "errorString": null
    }
}

Translate error code

This operation decodes any error string sent by an edge server to the browser. The data it returns helps you to understand the problem’s root cause. The response is an errorTranslatorContainer featuring error details or a separate errorString if the request fails.

GET /diagnostic-tools/v1/errortranslator{?errorCode}

Example: /diagnostic-tools/v1/errortranslator?errorCode=9.6f64d440.1318965461.2f2b078

Parameter Type Sample Description
Required
errorCode String 9.6f64d440.1318965461.2f2b078 Error code or reference number you want to translate, which typically appears on an error page.

Status 200 application/json

Response:

{
    "errorTranslator": {
        "url": "http&#x3a;&#x2f;&#x2f;etranslator.edgesuite.net&#x2f;ERR_READ_TIMEOUT",
        "httpResponseCode": "504",
        "dateTime": "Fri, Jun 26, 2015 17&#x3a;39 GMT",
        "epochTime": "1435340340",
        "clientIP": "NN.NN.NN.NN &#x28;CAMBRIDGE,MA,US&#x29;",
        "serverIP": "NN.NN.NN.NN &#x28;CAMBRIDGE,MA,US&#x29;",
        "originHostname": "example.download.akamai.com",
        "originIP": "NN.NN.NN.NN&#x28;ASHBURN,VA,US&#x29;",
        "userAgent": "Mozilla&#x2f;5.0 &#x28;Macintosh&#x3b; Intel Mac OS X 10_10_3&#x29; AppleWebKit&#x2f;537.36 &#x28;KHTML, like Gecko&#x29; Chrome&#x2f;43.0.2357.124 Safari&#x2f;537.36",
        "requestMethod": "GET",
        "reasonForFailure": "ERR_READ_TIMEOUT&#x7c;before_resp_hdrs",
        "logs": null,
        "errorString": null
    }
}

Get IP geolocation

This operation provides details for the location of an IP address. The response is an ipGeoLocationDataContainer with location details for the IP address provided.

GET /diagnostic-tools/v1/ipgeolocator{?ip}

Example: /diagnostic-tools/v1/ipgeolocator?ip=NNN.NNN.NNN.NNN

Parameter Type Sample Description
Required
ip String NNN.NNN.NNN.NNN IP Address

Status 200 application/json

Response:

{
    "ipGeoLocation": {
        "clientIp": "NNN.NNN.NNN.NNN",
        "countryCode": "US",
        "regionCode": "NY",
        "city": "NEWYORK",
        "dma": "501",
        "msa": "5602",
        "pmsa": "5600",
        "areaCode": "212",
        "latitude": "40.7500",
        "longitude": "-73.9967",
        "county": "NEWYORK",
        "continent": "NA",
        "fips": "36061",
        "timeZone": "EST",
        "network": null,
        "networkType": null,
        "zipCode": "10001-10014+10016-10041+10043-10045+10055+10060+10065",
        "throughput": "vhigh",
        "asNum": "1299",
        "errorString": null
    }
}

Verify if an IP is within the CDN

Verifies whether or not the IP provided belongs to the content delivery network. You would typically run this test before running the Akamai Translator on IP addresses that pass. The response provides a verifyCdnIPData object.

GET /diagnostic-tools/v1/verifycdnip{?ip}

Example: /diagnostic-tools/v1/verifycdnip?ip=NNN.NNN.NNN.NNN

Parameter Type Sample Description
Required
ip String NNN.NNN.NNN.NNN IP Address you want to determine is included in the Akamai network.

Status 200 application/json

Response:

{
    "isCdnIP"     : "No",
    "ip"          : "NN.NN.NN.NN",
    "errorString" : null
}

Data

Most response objects are wrappers featuring a single member that contains the relevant data. If the member references an array, any errorString that results from the request appears in the outer object. Otherwise the errorString appears as a member within the nested object.

The API represents all values as strings, except for unavailable or irrelevant values, which appear as null.

locationsContainer

Serves as a JSON wrapper for a locations list.

Sample JSON:

{
    "errorString": null,
    "locations": [
        "Cyberjaya, Malaysia",
        "Dublin, Ireland",
        "Losangeles, United States",
        "Madrid, Spain",
        "Moscow, Russian Federation",
        "Newyork, United States",
        "Osaka, Japan",
        "Paris, France",
        "Riodejaneiro, Brazil",
        "Seoul, South Korea",
        "Taiseng, Singapore",
        "Tokyo, Japan"
    ]
}

Members:

Member Type Description
errorString String Error message when requests for locations fail.
locations Array A list of locations (formatted as City, Country strings) that are valid to run mtr and dig tools.

digContainer

Serves as a JSON wrapper for dig output.

Sample JSON:

{
    "dig": {
        "answerSection": [
            {
                "domain": "www.example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "A",
                "ttl": "5",
                "value": "NN.NN.NN.NN"
            }
        ],
        "authoritySection": [
            {
                "domain": "example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "NS",
                "ttl": "86399",
                "value": "a.example.net."
            },
            {
                "domain": "example.com.",
                "preferenceValues": null,
                "recordClass": "IN",
                "recordType": "NS",
                "ttl": "86399",
                "value": "b.example.net."
            }
        ],
        "errorString": null,
        "hostname": "www.example.com.",
        "queryType": "A",
        "result": "\n; <<>> DiG 9.8.1-P1 <<>> www.example.com -t A\n..."
    }
}

Members:

digData

Member Type Description
answerSection record A record for the answering server.
authoritySection record Records for servers authorized to answer.
errorString String Error message if the dig execution or data fails.
hostname String Hostname from the query.
queryType String Query type of this dig, such as A, MX, or CNAME
result String Complete dig output as a multi-line string.

record

Member Type Description
domain String Domain name assigned to the server.
preferenceValues String When more than one SMTP server is available, a low number specifies a server to handle the transaction before trying servers with higher preference numbers.
recordClass String Record class, such as IN for internet.
recordType String Record type, such as A or CNAME.
ttl String Default time to live for the server, in seconds.
value String IP address for the server.

mtrContainer

Serves as a JSON wrapper for mtr output.

Sample JSON:

{
    "mtr": {
        "analysis": "",
        "avgLatency": "0.3",
        "destination": "www.example.com",
        "errorString": null,
        "hops": [
            {
                "avg": "0.3",
                "best": "0.2",
                "host": "NNNN:NNN:N:NNN::N",
                "last": "0.2",
                "loss": "0.0",
                "num": "1.|-",
                "sent": "10",
                "stDev": "0.0",
                "worst": "0.8"
            },
            {
                "avg": "4.6",
                "best": "0.3",
                "host": "XXN-NNN.XXXNN.example.net",
                "last": "0.3",
                "loss": "0.0",
                "num": "2.|-",
                "sent": "10",
                "stDev": "10.7",
                "worst": "33.9"
            },
            {
                "avg": "0.4",
                "best": "0.3",
                "host": "XX-N-N-N.XXXNN.example.net",
                "last": "0.6",
                "loss": "0.0",
                "num": "3.|-",
                "sent": "10",
                "stDev": "0.0",
                "worst": "0.6"
            }
        ],
        "host": "aNNN-NNN-NNN-NN.deploy.example.net",
        "packetLoss": "0.0",
        "source": null
    }
}

Members:

Member Type Description
analysis String Analysis of mtr data, reporting common anomalies such as loops.
avgLatency String Average latency, in seconds.
destination String Destination domain or IP address.
errorString String Error message if the mtr execution or data fails.
hops mtrHopInstance List of mtr hops.
host String Host domain or IP address.
packetLoss String Percent of packet loss from mtr.
source String Source IP address. A specific Akamai host name may appear as null.

mtrHopInstance

Member Type Description
avg String Average time for this hop, in seconds.
best String Best time for this hop, in seconds.
host String Host for this hop.
last String Time taken by last packet.
loss String Loss percentage at this hop.
num String Hop number.
sent String Number of packets sent.
stDev String Standard deviation.
worst String Worst time for this hop, in seconds.

ARLContainer

Serves as a JSON wrapper for arl data.

Sample JSON:

{
    "arl": {
        "cacheControl": null,
        "cpCode": "12345",
        "errorString": null,
        "originServer": "origin.example.com",
        "pragma": null,
        "serialNumber": "54321",
        "ttl": "Infinite",
        "typeCode": "Object changes when ARL changes"
    }
}

Members:

Member Type Description
cacheControl String Contents of the Cache-Control header.
cpCode String The Customer Provider code under which the request is tracked and billed.
errorString String Error message for the ARL request.
originServer String The origin server from which the cached object derives.
pragma String Contents of the Pragma header.
serialNumber String Identifies a server mapped to a region.
ttl String Remaining time to live for the cached object, in seconds.
typeCode String Describes how the server is configured.

errorTranslatorContainer

Serves as a JSON wrapper for errorTranslator output.

Sample JSON:

{
    "errorTranslator": {
        "clientIP": "NN.NN.NN.NN &#x28;CAMBRIDGE,MA,US&#x29;",
        "dateTime": "Fri, Jun 26, 2015 17&#x3a;39 GMT",
        "epochTime": "1435340340",
        "errorString": null,
        "httpResponseCode": "504",
        "logs": null,
        "originHostname": "example.download.akamai.com",
        "originIP": "NN.NN.NN.NN&#x28;ASHBURN,VA,US&#x29;",
        "reasonForFailure": "ERR_READ_TIMEOUT&#x7c;before_resp_hdrs",
        "requestMethod": "GET",
        "serverIP": "NN.NN.NN.NN &#x28;CAMBRIDGE,MA,US&#x29;",
        "url": "http&#x3a;&#x2f;&#x2f;etranslator.edgesuite.net&#x2f;ERR_READ_TIMEOUT",
        "userAgent": "Mozilla&#x2f;5.0 &#x28;Macintosh&#x3b; Intel Mac OS X 10_10_3&#x29; AppleWebKit&#x2f;537.36 &#x28;KHTML, like Gecko&#x29; Chrome&#x2f;43.0.2357.124 Safari&#x2f;537.36"
    }
}

Members:

Member Type Description
clientIP String Client IP.
dateTime String Date and time.
epochTime String Epoch time, in seconds.
errorString String Error message for the API layer, separate from any errors for which the API provides details.
httpResponseCode String HTTP response returned.
logs logLine Sample Ghost log for the request.
originHostname String Origin hostname.
originIP String Origin IP.
reasonForFailure String A description of the failure.
requestMethod String HTTP request method.
serverIP String Server IP.
url String The URL accessed by the client.
userAgent String User agent of the requesting browser.

logLine

Member Type Description
fields String Log line fields as name/value pairs.
logLine String Short description of log line.

ipGeoLocationDataContainer

Serves as a JSON wrapper for ipGeoLocationData output.

Sample JSON:

{
    "ipGeoLocation": {
        "areaCode": "212",
        "asNum": "1299",
        "city": "NEWYORK",
        "clientIp": "NNN.NNN.NNN.NNN",
        "continent": "NA",
        "countryCode": "US",
        "county": "NEWYORK",
        "dma": "501",
        "errorString": null,
        "fips": "36061",
        "latitude": "40.7500",
        "longitude": "-73.9967",
        "msa": "5602",
        "network": null,
        "networkType": null,
        "pmsa": "5600",
        "regionCode": "NY",
        "throughput": "vhigh",
        "timeZone": "EST",
        "zipCode": "10001-10014+10016-10041+10043-10045+10055+10060+10065"
    }
}

Members:

Member Type Description
ipGeoLocation ipGeoLocationData Location details for the IP address.

ipGeoLocationData

Member Type Description
areaCode String Area code.
asNum String Autonomous System number.
city String City, accurate to a 50-mile radius.
clientIp String IP address for which geolocation is requested.
continent String ISO–3188 continent code.
countryCode String ISO–3166 country code.
county String County.
dma String Designated Market Area.
errorString String Error message for the location request.
fips String Federal Information Processing Standard code.
latitude String Latitude.
longitude String Longitude.
msa String Metropolitan Statistical Area.
networkType String Network type.
network String Network name.
pmsa String Primary Metropolitan Statistical Area.
regionCode String ISO–3166 region code.
throughput Enumeration Data transfer speed. IPv4 traffic can appear as low, medium, high, or vhigh. IPv6 traffic always appears as low.
timeZone String Time zone.
zipCode String Zip code, allowing multiple values delimited with +, and dash-delimited ranges.

VerifyCdnIPData

Sample JSON:

{
    "errorString": null,
    "ip": "NN.NN.NN.NN",
    "isCdnIP": "No"
}

Members:

Member Type Description
errorString String Error message for the verification request.
ip String IP address for the verification request.
isCdnIP Enumeration Yes if the IP provided is part of this CDN, otherwise No.

Errors

This section shows you how to handle various kinds of error the API generates, and lists the range of HTTP codes the API produces for both success and error scenarios.

JSON problems

The Akamai API platform returns HTTP Problem error objects. 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/diagnostic-tools/v1/locations",
    "method": "GET",
    "serverIp": "NNN.NNN.NNN.NNN",
    "clientIp": "NNN.NNN.NNN.NNN",
    "requestId": "xxxxxxxx",
    "requestTime": "2015-04-16T14:56:52Z"
}

In most cases, the type and title provide enough information to understand the nature of the error.

Please be sure to reference the problem type when communicating with Akamai representatives or the Akamai Developer Community.

HTTP status codes

Code Description
200 Request OK
201 Resource created
401 Unauthorized request
402 Failed request
403 Forbidden
404 Resource not found
405 Method not allowed
415 Unsupported media type
422 Unprocessable entity
429 Too many requests
5xx Server error

Last modified: 4/14/2017