- Overview
- Resources
- API summary
- List HTTP Ingest dimensions
- List HTTP Ingest metrics
- Get HTTP Ingest data
- Get HTTP Ingest entry point switch information
- List HTTP Ingest Origin Shield dimensions
- List HTTP Ingest Origin Shield metrics
- Get HTTP Ingest Origin Shield data
- List RTMP Ingest dimensions
- List RTMP Ingest metrics
- Get RTMP Ingest data
- Get RTMP Ingest entry point switching information
- Data
- Errors
Media Reports API v1
Monitor and identify key trends of your Akamai Media Delivery solutions to access valuable insights to enhance business.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
The Media Reports API allows you to monitor and identify key trends of your live content delivered through the Akamai Intelligent Platform.
These first-mile reports provide information on ingest quality and availability for HTTP (HLS/HDS/DASH), RTMP, and Multi-CDN/Multi-Account-based ingests. They also report on accelerated streams.
Important Note: The following delivery-related API endpoints available in this document have been deprecated:
- Adaptive Media Delivery Reports
- Download Delivery Reports
- Wholesale Delivery Reports
- Object Delivery Reports
- RTMP Media Delivery Reports
These have now migrated to the Media Delivery Reports API.
Getting started
Review Get started on tools that Akamai provides.
Rate limiting
The Media Services Live API imposes a rate-limiting constraint of 20 requests per minute. Exceeding that limit results in a 429 error response. Consider this especially when calling successive operations as part of a loop. The following response headers provide rate limit information:
X-RateLimit-Limit: The maximum number of tokens allowed.X-RateLimit-Remaining: The number of tokens remaining.X-RateLimit-Next: The time when you can make one more request. For example:2018-05-11T07:04:40.004Z.
Once X-RateLimit-Remaining becomes 0, you get a 429 error the next time you make an API call.
If you do not make any more API calls after you receive a 429 error, X-RateLimit-Remaining gradually increases and becomes equal to X-RateLimit-Limit.
API workflow
For both HTTP and RTMP Ingest reports, you first need to obtain information on the available metrics and dimensions. You can use this information to select the required 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.
The sample request and response below shows how to generate an HTTP Ingest report. (See List HTTP Ingest 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 time at which content was consumed. This dimension is set 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 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 omitted. Also indicates the bit rate of the stream."
},
{
"id": 104,
"name": "File Type",
"description": "File type of the ingested object."
},
{
"id": 105,
"name": "Encoder IP",
"description": "IP address of encoder generating the stream."
},
{
"id": 106,
"name": "Entry Point",
"description": "IP address of the entry point on which stream is ingested."
},
{
"id": 107,
"name": "Stream Type",
"description": "Type of stream - Primary or Backup."
},
{
"id": 108,
"name": "Source IP",
"description": "Source IP/IAT IP"
},
{
"id": 109,
"name": "File Type",
"description": "File extension of the object requested. This is extracted from the URL of the requested object."
},
{
"id": 111,
"name": "File Extension",
"description": "File extension of the ingested object. This is extracted from the URL of the ingested object."
}
]
Step 2: Retrieve available metrics
Dimensions are measured by metrics.
You can run the API operation below to retrieve available metrics. Skip the step if you already know the metric IDs.
The sample request and response below shows how to generate an HTTP Ingest report. (See List HTTP Ingest metrics):
GET: /media-reports/v1/media-services-live/http-ingest/metrics
[
{
"id": 200,
"name": "Avg Bitrate",
"unit": "kbps",
"type": "bandwidth",
"description": "Average amount of data transferred in a unit of time, calculated in terms of 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 Bitrate",
"unit": "kbps",
"type": "bandwidth",
"description": "Average amount of data transferred in a unit of time, calculated in terms of 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.
The sample request and response below shows how to generate an HTTP Ingest report. The first GET line represents the URL template syntax. The second GET line is an actual sample URL. For more information, see (Get HTTP Ingest 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 Bitrate. The sample URL below 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 time at which content was consumed. This dimension is set automatically.",
"index": 0
},
{
"type": "metric",
"name": "Avg Bitrate",
"id": 200,
"description": "Average amount of data transferred in a unit of time, calculated in terms of 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
}
}
Resources
This section provides details on the API’s various operations. The following is a road map of the conceptual objects you deal with when interacting with the Media Reports API:
HLS/HDS/DASH Ingest reports: Reports on ingest quality and availability of HTTP-based Ingest (HLS/HDS/DASH). The reports also provide information on accelerated streams.
Stream Packaging reports: Reports of ingest quality and availability of RTMP streams that were converted to HLS/HDS/DASH.
Origin Shield Monitoring reports: Reports on ingest quality and availability of Multiple CDN and Multi-Account content.
Data stores: A data store is a collection of dimensions and metrics stored in a database that you can use to create reports.
Entry point switching: An entry point is an Akamai ingest server that receives streams from source. Entry point switching occurs when the ingest server experiences connectivity issues and the stream is routed to another server.
API summary
Download the RAML descriptors for this API.
| Operation | Method | Endpoint |
|---|---|---|
| HTTP Ingest | ||
| List HTTP Ingest dimensions | GET | /media-reports/ |
| List HTTP Ingest metrics | GET | /media-reports/ |
| Get HTTP Ingest data | POST | /media-reports/ |
| Get HTTP Ingest entry point switch information | GET | /media-reports/ |
| List HTTP Ingest Origin Shield dimensions | GET | /media-reports/ |
| List HTTP Ingest Origin Shield metrics | GET | /media-reports/ |
| Get HTTP Ingest Origin Shield data | POST | /media-reports/ |
| RTMP Ingest | ||
| List RTMP Ingest dimensions | GET | /media-reports/ |
| List RTMP Ingest metrics | GET | /media-reports/ |
| Get RTMP Ingest data | POST | /media-reports/ |
| Get RTMP Ingest entry point switching information | GET | /media-reports/ |
List HTTP Ingest dimensions
Retrieves all the dimensions available for HTTP Ingest (HLS/HDS/DASH).
GET /media-reports/
Status 200
application/json
Response Body:
[
{
"id": 99,
"name": "Source Type",
"description": "Source type - IAT or Encoder."
},
{
"id": 100,
"name": "Time",
"description": "Indicates the time at which content was consumed. This dimension is set 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 omitted. Also indicates the bit rate of the stream."
},
{
"id": 104,
"name": "File Type",
"description": "File type of the ingested object."
},
{
"id": 105,
"name": "Encoder IP",
"description": "IP address of encoder generating the stream."
},
{
"id": 106,
"name": "Entry Point",
"description": "IP address of the entry point at which stream is ingested."
},
{
"id": 107,
"name": "Stream Type",
"description": "Type of stream - Primary or Backup."
},
{
"id": 108,
"name": "Source IP",
"description": "Source IP/IAT IP"
},
{
"id": 109,
"name": "File Type",
"description": "File type of the object requested. This is extracted from the URL of the requested object."
},
{
"id": 111,
"name": "File Extension",
"description": "File Extension of the ingested object. This is extracted from the URL of the ingested object."
}
]
List HTTP Ingest metrics
Retrieves all the metrics available for HTTP Ingest (HLS/HDS/DASH).
GET /media-reports/
Status 200
application/json
Response Body:
[
{
"id": 200,
"name": "Avg Bitrate",
"unit": "kbps",
"type": "bandwidth",
"description": "Average amount of data transferred in a unit of time, calculated in terms of 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": "Total number of OK requests made to the entry point posting objects."
},
{
"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 Bitrate",
"unit": "kbps",
"type": "bandwidth",
"description": "Average amount of data transferred in a unit of time, calculated in terms of 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)."
}
]
Get HTTP Ingest data
Retrieves HTTP Ingest data for the given parameters.
POST /media-reports/
Sample: /media-reports/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
dimensions |
String | 1,2,3 |
Identifies dimensions with comma-separated IDs. |
endDate |
String | 2014-03-23T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
metrics |
String | 1,2,3 |
Identifies metrics with comma-separated IDs. |
startDate |
String | 2014-03-22T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
| Optional query parameters | |||
aggregation |
Number | 1440 |
The time period in which to group each data record, expressed as number of seconds. |
cpcodes |
String | 12345,67890 |
Specifies the set of comma-delimited CP codes for which to report data. |
filterParams |
String | [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] |
A UTF–8, URL-encoded JSON object representing filter parameters that limit reported data. See the FilterParams object for details on its structure. |
limit |
Number | 300 |
The number of rows to return from 1 to 10000. The default value is 300. |
offset |
Number | 0 |
The offset of the row from which reported data must start; used to request progressive batches of data. For example, you can make 10 requests for 1000 records by setting the overall limit to 100, then setting the offset to 0, 100, 200, and so on for each request. |
sortParams |
String | [{"type":"metric","order":"asc","id":40}] |
A UTF–8, URL-encoded JSON object representing sort parameters that rearrange reported data. See the SortParams object for details on its structure. |
streams |
String | 12345,67890 |
Identifies a set of reported streams as comma-separated ID values. |
Status 200
application/json
Response Body:
{
"columns": [
{
"type": "dimension",
"name": "Time",
"description": "Indicates the time at which content was consumed.",
"index": 0
},
{
"type": "metric",
"name": "Hits",
"description": "Total number of requests made to the entry point posting objects.",
"index": 1,
"aggregate": "46055"
}
],
"rows": [
[
"1471737600",
"158"
],
[
"1471737720",
"138"
],
[
"1471737840",
"183"
],
[
"1471737960",
"158"
],
[
"1471738080",
"163"
],
[
"1471738200",
"155"
]
],
"metaData": {
"startTimeInEpoch": 1471737600,
"offset": 0,
"limit": 300,
"timeZone": "GMT",
"hasMoreData": true,
"aggregation": 120,
"endTimeInEpoch": 1471860000
}
}
Get HTTP Ingest entry point switch information
Retrieves information about all the entry point switches that occurred in a given period.
GET /media-reports/
Sample: /media-reports/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
endDate |
String | 2014-03-23T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
startDate |
String | 2014-03-22T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
| Optional query parameters | |||
cpcodes |
String | 12345,67890 |
Specifies the set of comma-delimited CP codes for which to report data. |
limit |
Number | 300 |
The number of rows to return from 1 to 10000. The default value is 300. |
offset |
Number | 0 |
The offset of the row from which reported data must start; used to request progressive batches of data. For example, you can make 10 requests for 1000 records by setting the overall limit to 100, then setting the offset to 0, 100, 200, and so on for each request. |
streams |
String | 12345,67890 |
Identifies a set of reported streams as comma-separated ID values. |
Status 200
application/json
Response Body:
{
"columns": [
{
"index": 0,
"name": "Current Time",
"type": "dimension"
},
{
"index": 1,
"name": "Stream ID",
"type": "dimension"
},
{
"index": 2,
"name": "Entry Point Switch Time",
"type": "dimension"
},
{
"index": 3,
"name": "Old Entry Point",
"type": "dimension"
},
{
"index": 4,
"name": "New Entry Point",
"type": "dimension"
},
{
"index": 5,
"name": "Stream Type",
"type": "dimension"
}
],
"metaData": {
"aggregation": 120,
"endTimeInEpoch": 1487833200,
"hasMoreData": false,
"limit": 300,
"offset": 0,
"startTimeInEpoch": 1487826000,
"timeZone": "GMT"
},
"rows": [
[
"1487829360",
"266583",
"1487829240",
"198.18.52.238",
"198.18.52.240",
"Primary"
],
[
"1487830080",
"266583",
"1487829960",
"198.18.52.240",
"198.18.52.238",
"Primary"
],
[
"1487832120",
"266583",
"1487831520",
"198.18.52.238",
"198.18.52.240",
"Primary"
]
]
}
List HTTP Ingest Origin Shield dimensions
Retrieves all the dimensions available for HTTP Ingest(HLS/HDS/DASH).
GET /media-reports/
Status 200
application/json
Response Body:
[
{
"id": 5511,
"name": "ASN Name",
"description": "Name of the Autonomous System Number (ASN)."
},
{
"id": 5505,
"name": "CDN",
"description": "Name of the CDN provider."
},
{
"id": 5501,
"name": "CPCode",
"description": "Content provider code (CP code) is an identifier assigned to a contract and used for reporting, billing, and monitoring traffic served."
},
{
"id": 5507,
"name": "Client ASN",
"description": "Autonomous system number of an ISP."
},
{
"id": 5506,
"name": "Client Country",
"description": "Origin country of CDN."
},
{
"id": 5504,
"name": "Format",
"description": "Delivery format of the stream."
},
{
"id": 5509,
"name": "Origin Hostname",
"description": "CDN Hostname."
},
{
"id": 5508,
"name": "Publishing Geo",
"description": "GEO location of CDN host."
},
{
"id": 5502,
"name": "Stream Id",
"description": "Unique identifier associated with a stream."
},
{
"id": 5503,
"name": "Stream Type",
"description": "Type of stream - Primary or Backup."
},
{
"id": 5500,
"name": "Time",
"description": "Indicates the time at which the content was ingested."
}
]
List HTTP Ingest Origin Shield metrics
Retrieves all the metrics available for HTTP Ingest (HLS/HDS/DASH).
GET /media-reports/
Status 200
application/json
Response Body:
[
{
"id": 5525,
"name": "2xx Hits",
"type": "count",
"description": "Number of hits that returned response codes - 200 to 299 (Successful)."
},
{
"id": 5526,
"name": "3xx Hits",
"type": "count",
"description": "Number of hits that returned response codes - 300 to 399 (Redirection)."
},
{
"id": 5527,
"name": "4xx Hits",
"type": "count",
"description": "Number of hits that returned response codes - 400 to 499 (Client Error)."
},
{
"id": 5528,
"name": "5xx Hits",
"type": "count",
"description": "Number of hits that returned response codes - 500 to 599 (Server Error)."
},
{
"id": 5531,
"name": "Avg Download Time",
"unit": "seconds",
"type": "time",
"description": "Average time required to download media based on bandwidth, file size, and connection speed."
},
{
"id": 5533,
"name": "Avg Throughput",
"unit": "Mbps",
"description": "Rate of successful delivery of media. It is calculated as the total bytes delivered divided by the total time taken to serve the request."
},
{
"id": 5523,
"name": "Bandwidth",
"unit": "Mbps",
"description": "Total bandwidth usage including all HTTP response codes."
},
{
"id": 5522,
"name": "Bytes",
"description": "Total bytes transferred."
},
{
"id": 5520,
"name": "Hits",
"type": "count",
"description": "Total number of requests."
},
{
"id": 5545,
"name": "Hits [Download Time 0-2 Sec]",
"type": "count",
"description": "Total number of requests that took a download time of 0-2 seconds."
},
{
"id": 5546,
"name": "Hits [Download Time 2-4 Sec]",
"type": "count",
"description": "Total number of requests that took a download time of 2-4 seconds."
},
{
"id": 5547,
"name": "Hits [Download Time 4-6 Sec]",
"type": "count",
"description": "Total number of requests that took a download time of 4-6 seconds."
},
{
"id": 5548,
"name": "Hits [Download Time 6-8 Sec]",
"type": "count",
"description": "Total number of requests that took a download time of 6-8 seconds."
},
{
"id": 5549,
"name": "Hits [Download Time 8-10 Sec] ",
"type": "count",
"description": "Total number of requests that took a download time of 8-10 seconds."
},
{
"id": 5550,
"name": "Hits [Download Time > 10 Sec]",
"type": "count",
"description": "Total number of requests that took a download time of greater than 10 seconds."
},
{
"id": 5537,
"name": "Hits [Throughput 0-2 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 0-2 seconds."
},
{
"id": 5540,
"name": "Hits [Throughput 10-12 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 10-12 Mbps."
},
{
"id": 5541,
"name": "Hits [Throughput 12-15 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 12-15 Mbps."
},
{
"id": 5542,
"name": "Hits [Throughput 15-17 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 15-17 Mbps."
},
{
"id": 5543,
"name": "Hits [Throughput 17-20 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 17-20 Mbps."
},
{
"id": 5538,
"name": "Hits [Throughput 2-5 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 2-5 Mbps."
},
{
"id": 5539,
"name": "Hits [Throughput 5-10 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of 5-10 Mbps."
},
{
"id": 5544,
"name": "Hits [Throughput > 20 Mbps]",
"type": "count",
"description": "Total number of requests that had a throughput of over 20 Mbps."
},
{
"id": 5521,
"name": "Hits/sec",
"type": "count",
"description": "Number of hits per second."
},
{
"id": 5534,
"name": "Line Count",
"type": "count",
"description": "Line Count"
},
{
"id": 5529,
"name": "Other Hits",
"type": "count",
"description": "Number of requests that return responses that do not belong to the categories: 2xx, 3xx, 4xx, or 5xx. "
},
{
"id": 5535,
"name": "Success Bytes",
"unit": "bytes",
"type": "volume",
"description": "Volume of total bytes transferred in successful hits."
},
{
"id": 5532,
"name": "Throughput",
"description": "Rate of successful delivery of content. It is calculated as the total bytes delivered divided by the total time taken to serve the request."
},
{
"id": 5524,
"name": "Volume",
"unit": "MB",
"description": "Total number of megabytes transferred at the entry point."
},
{
"id": 5536,
"name": "Weighted Average Throughput",
"unit": "Mbps",
"description": "Rate of successful delivery of content weighted by daily bytes delivered."
}
]
Get HTTP Ingest Origin Shield data
Retrieves HTTP Ingest Origin Shield data for the given parameters.
POST /media-reports/
Sample: /media-reports/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
dimensions |
String | 1,2,3 |
Identifies dimensions with comma-separated IDs. |
endDate |
String | 2014-03-23T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
metrics |
String | 1,2,3 |
Identifies metrics with comma-separated IDs. |
startDate |
String | 2014-03-22T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
| Optional query parameters | |||
aggregation |
Number | 1440 |
The time period in which to group each data record, expressed as number of seconds. |
cpcodes |
String | 12345,67890 |
Specifies the set of comma-delimited CP codes for which to report data. |
filterParams |
String | [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] |
A UTF–8, URL-encoded JSON object representing filter parameters that limit reported data. See the FilterParams object for details on its structure. |
limit |
Number | 300 |
The number of rows to return from 1 to 10000. The default value is 300. |
offset |
Number | 0 |
The offset of the row from which reported data must start; used to request progressive batches of data. For example, you can make 10 requests for 1000 records by setting the overall limit to 100, then setting the offset to 0, 100, 200, and so on for each request. |
sortParams |
String | [{"type":"metric","order":"asc","id":40}] |
A UTF–8, URL-encoded JSON object representing sort parameters that rearrange reported data. See the SortParams object for details on its structure. |
streams |
String | 12345,67890 |
Identifies a set of reported streams as comma-separated ID values. |
Status 200
application/json
Response Body:
{
"columns": [
{
"type": "dimension",
"name": "CPCode",
"description": "Identifier assigned to a contract and used for reporting, billing, and monitoring traffic served.",
"index": 0
},
{
"type": "dimension",
"name": "Stream Id",
"description": "Unique identifier associated with a stream generated by the Akamai provisioning workflow.",
"index": 1
},
{
"type": "metric",
"name": "Hits",
"description": "Total number of requests made to the entry point posting objects.",
"index": 2,
"aggregate": "88"
},
{
"type": "metric",
"name": "Hits/sec",
"description": "Number of hits per second to entry point servers.",
"index": 3,
"aggregate": "1.47"
},
{
"type": "metric",
"name": "Bandwidth",
"description": "Total bandwidth usage at the entry point, including all HTTP response codes.",
"index": 3,
"aggregate": "8.67",
"unit": "Mbps"
}
],
"rows": [
"686645",
"12345",
"88",
"1.47",
"8.67"
],
"metaData": {
"startTimeInEpoch": 1522980000,
"offset": 0,
"limit": 300,
"timeZone": "GMT",
"hasMoreData": false,
"aggregation": 60,
"endTimeInEpoch": 1522984260
}
}
List RTMP Ingest dimensions
Retrieves all the dimensions available for RTMP Ingest.
GET /media-reports/
Status 200
application/json
Response Body:
[
{
"id": 209,
"name": "Stream Type",
"description": "Type of stream - Primary (actual) or Backup."
},
{
"id": 210,
"name": "Source Type",
"description": "Source type - IAT or Encoder."
},
{
"id": 200,
"name": "Time",
"description": "Indicates the time at which content was consumed. This dimension is set automatically."
},
{
"id": 201,
"name": "CP Code",
"description": "Identifier assigned to a contract associated with a particular stream."
},
{
"id": 202,
"name": "Stream ID",
"description": "Unique identifier associated with a stream generated by the Akamai provisioning workflow."
},
{
"id": 203,
"name": "Unique End Point",
"description": "The URL path after Stream ID in the ingest URL. Indicates bit rate of the stream."
},
{
"id": 204,
"name": "Encoder IP",
"description": "IP address of encoder generating the stream."
},
{
"id": 205,
"name": "Authentication Scheme",
"description": "Stream authentication scheme used. Values displayed can be Adobe/Akamai/Octoshape."
},
{
"id": 206,
"name": "Entry Point",
"description": "IP address of the entry point at which stream is ingested."
},
{
"id": 207,
"name": "File Type",
"description": "File type of the ingested stream."
},
{
"id": 208,
"name": "Encoder IP",
"description": "IP address of encoder generating the stream."
}
]
List RTMP Ingest metrics
Retrieves all the metrics available for MSL RTMP Ingest.
GET /media-reports/
Status 200
application/json
Response Body:
[
{
"id": 230,
"name": "Avg Bitrate",
"unit": "kbps",
"type": "bandwidth",
"description": "Average amount of data transferred in a unit of time; calculated in terms of bits per second; and expressed in kbps, Mbps, Gbps etc."
},
{
"id": 231,
"name": "Query Agg",
"type": "count",
"description": "Query Agg"
},
{
"id": 232,
"name": "Avg Latency",
"unit": "ms",
"type": "time",
"description": "Indicates the delay between encoder and entry point when sending a unit of media payload."
},
{
"id": 233,
"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 Encoder."
},
{
"id": 234,
"name": "Bytes Transferred",
"unit": "kbps",
"type": "bandwidth",
"description": "Bytes Transferred"
},
{
"id": 235,
"name": "Avg Bitrate",
"unit": "kbps",
"type": "bandwidth",
"description": "Average amount of data transferred in a unit of time; calculated in terms of bits per second; and expressed in kbps, Mbps, Gbps etc."
},
{
"id": 236,
"name": "Avg Path Time",
"unit": "ms",
"type": "time",
"description": "Average time taken from source to destination."
}
]
Get RTMP Ingest data
Retrieves RTMP Ingest data for the given parameters.
POST /media-reports/
Sample: /media-reports/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
dimensions |
String | 1,2,3 |
Identifies dimensions with comma-separated IDs. |
endDate |
String | 2014-03-23T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
metrics |
String | 1,2,3 |
Identifies metrics with comma-separated IDs. |
startDate |
String | 2014-03-22T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
| Optional query parameters | |||
aggregation |
Number | 1440 |
The time period in which to group each data record, expressed as number of seconds. |
cpcodes |
String | 12345,67890 |
Specifies the set of comma-delimited CP codes for which to report data. |
filterParams |
String | [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] |
A UTF–8, URL-encoded JSON object representing filter parameters that limit reported data. See the FilterParams object for details on its structure. |
limit |
Number | 300 |
The number of rows to return from 1 to 10000. The default value is 300. |
offset |
Number | 0 |
The offset of the row from which reported data must start; used to request progressive batches of data. For example, you can make 10 requests for 1000 records by setting the overall limit to 100, then setting the offset to 0, 100, 200, and so on for each request. |
sortParams |
String | [{"type":"metric","order":"asc","id":40}] |
A UTF–8, URL-encoded JSON object representing sort parameters that rearrange reported data. See the SortParams object for details on its structure. |
streams |
String | 12345,67890 |
Identifies a set of reported streams as comma-separated ID values. |
Status 200
application/json
Response Body:
{
"columns": [
{
"type": "dimension",
"name": "Time",
"description": "Indicates the time at which content was consumed. This dimension is set automatically.",
"index": 0
},
{
"type": "metric",
"name": "Hits",
"description": "Total number of requests made to the entry point posting objects.",
"index": 1,
"aggregate": "46055"
}
],
"rows": [
[
"1471737600",
"158"
],
[
"1471737720",
"138"
],
[
"1471737840",
"183"
],
[
"1471737960",
"158"
],
[
"1471738080",
"163"
],
[
"1471738200",
"155"
]
],
"metaData": {
"startTimeInEpoch": 1471737600,
"offset": 0,
"limit": 300,
"timeZone": "GMT",
"hasMoreData": true,
"aggregation": 120,
"endTimeInEpoch": 1471860000
}
}
Get RTMP Ingest entry point switching information
Retrieves information about all the entry point switches that occurred in a given period.
GET /media-reports/
Sample: /media-reports/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
dimensions |
String | 1,2,3 |
Identifies dimensions with comma-separated IDs. |
endDate |
String | 2014-03-23T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
metrics |
String | 1,2,3 |
Identifies metrics with comma-separated IDs. |
startDate |
String | 2014-03-22T15:30Z |
The timestamp string in ISO 8601 format yyyy-MM-ddTHH:mmZ or yyyy-MM-ddTHH:mm+HH:mm. |
| Optional query parameters | |||
cpcodes |
String | 12345,67890 |
Specifies the set of comma-delimited CP codes for which to report data. |
filterParams |
String | [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] |
A UTF–8, URL-encoded JSON object representing filter parameters that limit reported data. See the FilterParams object for details on its structure. |
limit |
Number | 300 |
The number of rows to return from 1 to 10000. The default value is 300. |
offset |
Number | 0 |
The offset of the row from which reported data must start; used to request progressive batches of data. For example, you can make 10 requests for 1000 records by setting the overall limit to 100, then setting the offset to 0, 100, 200, and so on for each request. |
sortParams |
String | [{"type":"metric","order":"asc","id":40}] |
A UTF–8, URL-encoded JSON object representing sort parameters that rearrange reported data. See the SortParams object for details on its structure. |
streams |
String | 12345,67890 |
Identifies a set of reported streams as comma-separated ID values. |
Status 200
application/json
Response Body:
{
"columns": [
{
"index": 0,
"name": "Current Time",
"type": "dimension"
},
{
"index": 1,
"name": "Stream ID",
"type": "dimension"
},
{
"index": 2,
"name": "Entry Point Switch Time",
"type": "dimension"
},
{
"index": 3,
"name": "Old Entry Point",
"type": "dimension"
},
{
"index": 4,
"name": "New Entry Point",
"type": "dimension"
},
{
"index": 5,
"name": "Stream Type",
"type": "dimension"
}
],
"metaData": {
"aggregation": 120,
"endTimeInEpoch": 1487833200,
"hasMoreData": false,
"limit": 300,
"offset": 0,
"startTimeInEpoch": 1487826000,
"timeZone": "GMT"
},
"rows": [
[
"1487829360",
"266583",
"1487829240",
"198.18.52.238",
"198.18.52.240",
"Primary"
],
[
"1487830080",
"266583",
"1487829960",
"198.18.52.240",
"198.18.52.238",
"Primary"
],
[
"1487832120",
"266583",
"1487831520",
"198.18.52.238",
"198.18.52.240",
"Primary"
]
]
}
Data
This section describes Media Reports API’s various data structures.
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. |
Report
Encapsulates a media data report for various products.
Download schema:
mediaServicesData.json
Sample GET response:
{
"columns": [
{
"type": "dimension",
"name": "Time",
"description": "Indicates the time at which content was consumed.",
"index": 0
},
{
"type": "metric",
"name": "Hits",
"description": "Total number of requests made to the entry point posting objects.",
"index": 1,
"aggregate": "46055"
}
],
"rows": [
[
"1471737600",
"158"
],
[
"1471737720",
"138"
],
[
"1471737840",
"183"
],
[
"1471737960",
"158"
],
[
"1471738080",
"163"
],
[
"1471738200",
"155"
]
],
"metaData": {
"startTimeInEpoch": 1471737600,
"offset": 0,
"limit": 300,
"timeZone": "GMT",
"hasMoreData": true,
"aggregation": 120,
"endTimeInEpoch": 1471860000
}
}
Report members
| Member | Type | Required | Description |
|---|---|---|---|
columns |
Report. |
✓ | Provides context for each element listed within corresponding rows. |
metaData |
Report. |
✓ | Reflects the set of parameter values included in the request that determines this report’s results. |
rows |
Array | ✓ | Encapsulates the report’s two-dimensional table data. If there is no data to report, the array is empty. |
Report.columns[]: Provides context for each element listed within corresponding rows. |
|||
aggregate |
String | ○ | Provides an aggregate value for the dimension or metric expressed in string format. For example, for type: metric and name: Hits, the information returned would be the number of hits for each row of data. |
description |
String | ✓ | Provides information about the relevant dimension or metric. |
index |
Number | ✓ | Positions each column within the table. |
name |
String | ✓ | Depending on the type, provides the name of the relevant dimension or metric. |
type |
Enumeration | ✓ | Type of data: dimension or metric. |
Report.metaData: Reflects the set of parameter values included in the request that determines this report’s results. |
|||
aggregation |
Number | ✓ | The time span included in each record, expressed in seconds. |
endTimeInEpoch |
Number | ✓ | The end of the requested time range, in epoch seconds. |
hasMoreData |
Boolean | ✓ | Indicates that a constrained set of requested data does not represent the entire set. |
limit |
Number | ✓ | The maximum number of requested data rows. |
offset |
Number | ✓ | The offset of the row from which the data should start. Used with overall limit, it reflects where a batch of data starts. For example, setting both offset and limit to 100 selects rows 101–200 from the overall results. |
startTimeInEpoch |
Number | ✓ | The start of the requested time range, in epoch seconds. |
timeZone |
String | ✓ | Identifies the time zone from which the request was made. |
FilterParams
Encapsulates filtering parameters that are wrapped in an array, URL-encoded, and passed in with GET requests using the filterParams query parameter.
Download schema:
filter-params.json
Sample non-encoded parameter value, expanded:
[
{
"condition": "in",
"id": 4,
"type": "dimension",
"values": [
"GB"
]
},
{
"condition": "gt",
"id": 155,
"type": "metric",
"values": [
16
]
}
]
FilterParams members
| Member | Type | Required | Description |
|---|---|---|---|
condition |
Enumeration | ✓ | The condition specifier. For dimensions: in, nin (in or not in), contains, ncontains (does or doesn’t contain), starts, nstarts (does or doesn’t start with), ends, nends (does or doesn’t end with). For metrics: eq, neq (equal or not), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal). |
id |
Integer | ✓ | Identifies each dimension or metric filtering entity. |
type |
Enumeration | ✓ | Specifies whether the provided id parameter is a dimension or a metric. |
values |
Array | ✓ | List of values used to filter the result. Values represent either inclusions or exclusions, depending on what the condition parameter specifies. |
SortParams
Encapsulates sorting parameters that are wrapped in an array, URL-encoded, and passed in with GET requests using the sortParams query parameter.
Download schema:
sort-params.json
Sample non-encoded parameter value, expanded:
[
{
"id": 40,
"order": "asc",
"type": "metric"
}
]
SortParams members
| Member | Type | Required | Description |
|---|---|---|---|
id |
Integer | ✓ | The ID of the sorting entity. The sorting entity should also be part of the query parameter metrics or dimensions. |
order |
Enumeration | ✓ | Either asc for ascending or desc for descending sort order. |
type |
Enumeration | ✓ | Indicates if the id parameter is a dimension or a metric. |
Errors
This section provides details on the format of error response objects the Media Reports API generates. It also lists the range of HTTP response codes for both error and success cases.
Error response codes
API endpoints routinely respond with failure codes to a wide range of problems with the integrity of the data. The API returns HTTP response codes that correspond to the httpStatus element in the JSON response, eliminating the need to query the header for the response code. For all non–2xx HTTPS status codes, the API responds with a JSON object such as the following:
{
"httpStatus": 400,
"instance": "49046f42-f51f-403b-be60-6fb8179aa1d2",
"detail": "Start date and End date are same",
"title": "Bad Request"
}
HTTP status codes
The API produces the following set of HTTP status codes for both success and failure scenarios:
| Code | Description |
|---|---|
| 200 | OK. If the report yields an empty data set, the response yields an empty set of rows. |
| 400 | Bad input parameter. The Error detail should identify the cause. |
| 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. |
Last modified: 7/24/2018