API workflow

First, you need to obtain information on the available metrics and dimensions. You can use this information to select specific combinations and call the relevant URLs to create customized reports tailored to your specifications.

Step 1. Retrieve available dimensions

You can extract a dimension from a key-value pair, URI Components or strings in log data.

You can run the API operation below to retrieve available dimensions. Skip the step if you already know the dimension IDs.

This sample request and response shows how to generate a Media Services Live 4 ingest report (see List Media Services Live 4 dimensions).

GET: /media-reports/v1/media-services-live/http-ingest/dimensions

[
    {
        "id": 99,
        "name": "Source Type",
        "description": "Source type - IAT or Encoder."
    },
    {
        "id": 100,
        "name": "Time",
        "description": "Indicates the consumption time of the content. Akamai sets this dimension automatically."
    },
    {
        "id": 101,
        "name": "CP Code",
        "description": "Identifier assigned to a contract associated with a particular stream."
    },
    {
        "id": 102,
        "name": "Stream ID",
        "description": "Unique identifier associated with a stream generated by the Akamai provisioning workflow."
    },
    {
        "id": 103,
        "name": "Unique End Point",
        "description": "The URL path after the Stream ID in the ingest URL. For manifest files, the file name is part of the Unique End Point. For segment requests, the file name (last path element) is left out. This also indicates the bit rate of the stream."
    },
    {
        "id": 104,
        "name": "File Type",
        "description": "The ingested object's file type."
    },
    {
        "id": 105,
        "name": "Encoder IP",
        "description": "IP address of encoder generating the stream."
    },
    {
        "id": 106,
        "name": "Entry Point",
        "description": "IP address for the entry point. Akamai ingested the stream from this entry point."
    },
    {
        "id": 107,
        "name": "Stream Type",
        "description": "The stream type, either `Primary` or `Backup`."
    },
    {
        "id": 108,
        "name": "Source IP",
        "description": "Source IP or Source IAT IP"
    },
    {
        "id": 109,
        "name": "File Type",
        "description": "File extension of the object requested. The system extracts this from the URL of the requested object."
    },
    {
        "id": 111,
        "name": "File Extension",
        "description": "File extension of the ingested object. The system extracts this from the URL of the ingested object."
    }
]

Step 2. Retrieve available metrics

​Akamai​ measures dimensions using metrics.

You can run the API operation below to retrieve available metrics. Skip the step if you already know the metric IDs.

This sample request and response shows how to generate a Media Services Live 4 ingest report (see List Media Services Live 4 metrics).

GET: /media-reports/v1/media-services-live/http-ingest/metrics

[
    {
        "id": 200,
        "name": "Avg Bit rate",
        "unit": "kbps",
        "type": "bandwidth",
        "description": "Average amount of data transferred in a unit of time, calculated in bits per second. Expressed in kbps, Mbps, Gbps etc."
    },
    {
        "id": 201,
        "name": "Error Rate",
        "unit": "%",
        "type": "percent",
        "description": "Rate of errors occurring in a unit of time. Expressed as a percentage."
    },
    {
        "id": 202,
        "name": "Ingest Hits",
        "type": "count",
        "description": "Total number of requests made to the entry point posting objects."
    },
    {
        "id": 203,
        "name": "2xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 200 to 299 (Successful)"
    },
    {
        "id": 204,
        "name": "3xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 300 to 399 (Redirection)"
    },
    {
        "id": 205,
        "name": "4xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 400 to 499 (Client Error)"
    },
    {
        "id": 206,
        "name": "5xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 500 to 599 (Server Error)"
    },
    {
        "id": 207,
        "name": "Avg Latency",
        "unit": "ms",
        "type": "time",
        "description": "Indicates the delay between encoder and entry point when sending a unit of media payload."
    },
    {
        "id": 208,
        "name": "Avg Packet Loss",
        "unit": "%",
        "type": "percent",
        "description": "Measures the quality of connection between encoder and entry Point. Provides connection level ratio of data packets(bytes) lost to the data packets(bytes) sent by the encoder."
    },
    {
        "id": 209,
        "name": "Ingest Hits",
        "type": "count",
        "description": "Total number of requests made to the entry point posting objects."
    },
    {
        "id": 210,
        "name": "Success Ingest Hits",
        "type": "count",
        "description": "Success Hits"
    },
    {
        "id": 212,
        "name": "Error Rate",
        "unit": "%",
        "type": "percent",
        "description": "Rate of errors occurring in a unit of time. Expressed as a percentage."
    },
    {
        "id": 213,
        "name": "Avg Path Time",
        "unit": "ms",
        "type": "time",
        "description": "Average time taken from source to destination."
    },
    {
        "id": 214,
        "name": "Avg Bit rate",
        "unit": "kbps",
        "type": "bandwidth",
        "description": "Average amount of data transferred in a unit of time, calculated in bits per second. Expressed in kbps, Mbps, Gbps etc."
    },
    {
        "id": 215,
        "name": "2xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 200 to 299 (Successful)"
    },
    {
        "id": 216,
        "name": "3xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 300 to 399 (Redirection)"
    },
    {
        "id": 217,
        "name": "4xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 400 to 499 (Client Error)"
    },
    {
        "id": 218,
        "name": "5xx Ingest Hits",
        "type": "count",
        "description": "Number of requests made to the entry point posting objects that returned response codes - 500 to 599 (Server Error)"
    }
]

Step 3. Retrieve data

You can retrieve data for a given CP code using the API call shown below.

This sample request and response shows how to generate a Media Services Live 4 ingest report. The first GET line represents the URL template syntax. The second GET line represents an actual sample URL (see Get Media Services Live 4 data):

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

Assume that the dimension ID 100 represents Time and the metric ID 200 represents the metric Avg Bit rate. This sample URL reports on average bit rate by time for a period starting 12/01/2015:00:00 to 12/01/2015:05:00 for a CP code 12345:

GET: /media-reports/v1/media-services-live/http-ingest/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": "Indicates the consumption time of the content. Akamai sets this dimension automatically.",
            "index": 0
        },
        {
            "type": "metric",
            "name": "Avg Bit rate",
            "id": 200,
            "description": "Average amount of data transferred in a unit of time, calculated in bits per second. Expressed in kbps, Mbps, Gbps etc.",
            "index": 1,
            "unit": "kbps"
        }
    ],
    "rows": [
        [
            "1529891640",
            "1605.884392"
        ],
        [
            "1529891760",
            "1618.015465"
        ],
        [
            "1529891880",
            "1596.447969"
        ]
    ],
    "metaData": {
        "startTimeInEpoch": 1529891640,
        "offset": 0,
        "limit": 300,
        "timeZone": "GMT",
        "hasMoreData": false,
        "aggregation": 120,
        "endTimeInEpoch": 1529898840
    }
}