The Media Reports API

Media Reports help you monitor and identify key trends of your Akamai Media Delivery solutions. Its one-stop, easy reporting interface within Luna Control Center gives you access to valuable insights to enhance your business by optimizing your streaming content, software downloads, and object delivery.

The Media Reports API provides an easy interface to manage how Akamai processes data for various media delivery products.

The REST API responds to requests with standard HTTP status codes. Error messages are embedded in the JSON response in the event of a validation failure or when the API fails to process your request.

Getting Started

Visit the OPEN API Introduction section to get started and make Akamai OPEN API calls.

URL Structure

https://{BASE_URL}/media-reports/v1

Generate BASE_URL using the Manage APIs tool in Akamai Luna Control Center.

Sample Usage: Steps to Retrieve Data

Step 1: Retrieve Available Dimensions

A dimension is an umbrella under which metrics are grouped, filtered and aggregated.

It can be extracted from a key-value pair, URI Components or strings.

Run the API operation below to retrieve available dimensions. Skip this step, if you already know the dimension IDs.

Here is a sample request and response (Using Adaptive Media Delivery, as an example):

GET: /media-reports/v1/adaptive-media-delivery/dimensions

  • Response 200 (application/json)
[
    {
        "id": 1,
        "name": "Time",
        "description": "The time dimension"
    },
    {
        "id": 24,
        "name": "Country",
        "description": "Country Name"
    },
    {
        "id": 31,
        "name": "Partner Hostname",
        "description": "partner_hostname"
    }
]

Step 2: Retrieve Available Metrics

Dimensions are measured by metrics.

Run the API operation below to retrieve available metrics. Skip this step, if you already know the metric IDs.

A sample request and response is shown below (Using Adaptive Media Delivery, as an example):

GET: /media-reports/v1/adaptive-media-delivery/metrics

  • Response 200 (application/json)
[
    {
        "id": 116,
        "name": "Midgress Bytes",
        "unit": "bytes",
        "type": "volume",
        "description": "midgress_bytes"
    },
    {
        "id": 9,
        "name": "Midgress Hits",
        "unit": null,
        "type": "count",
        "description": "midgress_hits"
    },
    {
        "id": 10,
        "name": "Midgress Object Bytes",
        "unit": "bytes",
        "type": "volume",
        "description": "midgress_objbytes"
    }
]

Step 3: Retrieve Data

Data for a given CP code can be retrieved using the API call shown below.

Here is a sample request and response (Using Adaptive Media Delivery, as an example):

GET: /media-reports/v1/adaptive-media-delivery/data(?startDate,endDate,aggregation,dimensions,metrics,cpcodes,ipVersion,limit,offset,filterParams,sortParams,deliveryOption,deliveryFormat,deliveryType)

Let’s assume that the dimension ID 1 represents Time and the metric ID 107 represents the metric Edge Volume. A sample call to fetch Edge Volume by Time for a period 12/01/2015:00:00 to 12/01/2015:05:00 for a cpcode 12345 is shown below along with its response:

GET: /media-reports/v1/adaptive-media-delivery/data?startDate=12/01/2015:00:00&endDate=12/01/2015:05:00&cpcodes=12345&ipVersion="ipv41"&limit=1000&offset=0&deliveryOption="http"&deliveryFormat="hls"&deliveryType="live"&dimensions=1&metrics=107

  • Response 200(application/json)
[
    {
        "columns": [
            {
                "type": "dimension",
                "name": "Time",
                "description": "time",
                "index": 0
            },
            {
                "type": "metric",
                "name": "Edge Volume",
                "description": "Edge Volume",
                "index": 1,
                "aggregate": "191.79",
                "peak": "101.09",
                "unit": "MB"
            }
        ],
        "rows": [
            [ "1448931300", "101.09" ],
            [ "1448937600", "10.06" ],
            [ "1448943000", "80.64" ]
        ],
        "metaData": {
            "aggregation": 300,
            "limit": 1000,
            "startTimeInEpoch": 1448928000,
            "hasMoreData": false,
            "timeZone": "GMT",
            "offset": 0,
            "reportPack": "Test report pack",
            "endTimeInEpoch": 1448946000
        }
    }
]

Response Codes

API calls can return any of the following response codes:

Code Description
200 OK.
204 No data.
400 Bad input parameter. Error message should indicate which one and why.
401 Authentication failure.
403 Authorization failure.
404 Resource not found.
405 Request method not expected (generally should be GET).
409 Conflict.
410 Requested resource is no longer available.
411 Content-length header not specified.
413 Request body exceeds maximum allowable size.
423 Requested resource is locked.
429 Too many requests.
500 Internal server error; unexpected condition.
501 Not supported.
503 Too many requests; service is temporarily unavailable.
507 Data size is over allowable limit.

The error JSON below is returned for all non–2xx HTTPS status codes. The returned HTTP response code corresponds to the httpStatus element in the JSON response. This enables the caller to not have to query the header for the response code.

HTTP/1.1 404 Not Found

Content-Type: application/json
Reply Body:
{
    "httpStatus": 404,
    "detail": "additional non-http specific info where relevant",
    "title": "Resource not found"
}

Important Notes

Encoding of Request Parameters

All request parameter values must be UTF–8 encoded.

Headers

The HTTP authorization header MUST be included in the request message.

Authorization: EG1-HMAC-SHA256 client_token=[value];access_token=[value];timestamp=[value];nonce=[value];signature=[value]
  • This is standard RFC 2616, with proprietary specifics.

Here is an example of an HTTP authorization header, with line breaks added for readability:

Authorization: EG1-HMAC-SHA256 client_token=akaa-275ca6de04b11b91-cf46074bf3b52950;
access_token=akaa-d6cfbdb2d0594ae4-ad000cf3a5473a08;timestamp=20130817T02:49:13+0000;
nonce=dd9957e2-4fe5-48ca-8d32-16a772ac6d8f;signature=Q3uWyssCz9qsNxekOX+PXP0WrtGT+J5qd6ssN1UmUmw=

Using Country Codes

The Media Reports API allows you to work with geographic lists of country codes. Here, you must use the codes found on the Akamai EdgeScape country codes page, in Akamai Luna Control Center (SupportUser and Developer GuidesEdgeScapeData CodesCountry Codes).

Rate Limiting–429 Status

Media Reports API endpoints are subject to a rate-limiting constraint, which is currently set at ten requests per minute. When this limit is reached, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop.