The Media Delivery Reports API

Media Delivery 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 Delivery Reports API v1 provides an easy interface to manage how Akamai processes data for various media delivery products.

This API replaces much of the media delivery functionality of the Media Reports API, but renamed and restarting at v1. Other functions of the older API will be re-deployed as a third API, separately from this one.

Error messages for failure to process requests, or validation failures are embedded in the JSON response.

Getting started

Before using the Media Delivery Reports API for the first time:

  • Contact your Akamai representative to enable it for your account.

  • 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=
    
  • Remember that all request parameter values must be UTF–8 encoded.

Rate limiting

The Media Reports API imposes a rate limiting constraint of five requests per minute. When calling successive operations as part of a loop, you need to consider that exceeding the limit results in a 429 error response. The API responds with the following HTTP headers to provide context over how close it is getting to the limit:

  • X-RateLimit-Limit: Five requests per minute.

  • X-RateLimit-Remaining: Number of remaining requests allowed during the period.

  • X-RateLimit-Reset: Timestamp indicating reset of request limit back to the higher limit.

Sample Usage: Steps to retrieve data

To query a report, you will first need to obtain data store metadata with information on the metrics and dimensions grouped together. You can then choose the required comnbinations to create customized reports tailored to your specifications.

Step 1: Get data stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query.

  • Run the API operation below to retrieve available collection of data stores:

Below is a sample request and response (See List Adaptive Media Delivery Data Stores):

GET: /media-reports/v2/adaptive-media-delivery/data-stores

[  
    {  
        "id":3,
        "name":"Usage AMD",
        "type":"standard",
        "description":"ma_usage_adaptive_-_D_time",
        "dimensions":[  
            {  
                "id":1,
                "name":"Time",
                "description":"Indicates the time at which content was consumed.This dimension is set automatically.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            },
            {  
                "id":2,
                "name":"CPCode",
                "description":"Content Provider Code (CPCode) is an identifier assigned to a contract and used for reporting, billing and monitoring traffic served.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            }
        ],
        "metrics":[  
            {  
                "id":1,
                "name":"Play Duration",
                "unit":"seconds",
                "type":"time",
                "description":"Total time duration for which your media was played.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            },
            {  
                "id":2,
                "name":"Edge + Midgress",
                "unit":"GB",
                "type":"volume",
                "description":"Sum of Edge And Midgress Volume",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            }
        ],
        "aggregationInSeconds":86400,
        "purgeIntervalInDays":90,
        "maxQueryDurationInMinutes":44640
    },
    {  
        "id":303,
        "name":"trafficsummary_-_F_time",
        "type":"standard",
        "description":"trafficsummary_-_F_time",
        "dimensions":[  
            {  
                "id":600,
                "name":"Time",
                "description":"Indicates the time at which content was consumed.This dimension is set automatically.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            },
            {  
                "id":601,
                "name":"CP Code",
                "description":"Content Provider Code (CPCode) is an identifier assigned to a contract and used for reporting, billing and monitoring traffic served.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            }
        ],
        "metrics":[  
            {  
                "id":608,
                "name":"Midgress Hits",
                "unit":"Count",
                "type":"count",
                "description":"Midgress traffic includes hits from edge servers to other edge servers.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            },
            {  
                "id":609,
                "name":"Midgress Hits/sec",
                "unit":"Hits/sec",
                "type":"count",
                "description":"The total number of hits from Edge Servers to other Edge Servers, for the CP code(s) and time period selected.",
                "group":[  
                    {  
                        "id":-1,
                        "name":"OTHERS",
                        "description":"OTHERS"
                    }
                ]
            }
        ],
        "aggregationInSeconds":300,
        "purgeIntervalInDays":1,
        "maxQueryDurationInMinutes":1440
    }
]

Step 2: Retrieve data

This sample request and response shows how to fetch Edge Volume by Time for a specific CP code for the period 12/01/2015:00:00 to 12/01/2015:05:00with dimension ID 1 representing Time and metric ID 107 representing the metric Edge Volume for CP code 12345(See Get Adaptive Media Delivery Data):

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

[
    {
        "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": "GB"
            }
        ],
        "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
        }
    }
]

Last modified: 6/14/2018