Media Reports API v1

Monitor and identify key trends of your Akamai Media Delivery solutions to access valuable insights to enhance business.

Learn more:


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/v1/media-services-live/http-ingest/dimensions
List HTTP Ingest metrics GET /media-reports/v1/media-services-live/http-ingest/metrics
Get HTTP Ingest data POST /media-reports/v1/media-services-live/http-ingest/data{?dimensions,metrics,startDate,endDate,cpcodes,limit,offset,aggregation,filterParams,sortParams,streams}
Get HTTP Ingest entry point switch information GET /media-reports/v1/media-services-live/http-ingest/ep-switch/data{?startDate,endDate,cpcodes,limit,offset,streams}
List HTTP Ingest Origin Shield dimensions GET /media-reports/v1/media-services-live/http-ingest/origin-shield/dimensions
List HTTP Ingest Origin Shield metrics GET /media-reports/v1/media-services-live/http-ingest/origin-shield/metrics
Get HTTP Ingest Origin Shield data POST /media-reports/v1/media-services-live/http-ingest/origin-shield/data{?dimensions,metrics,startDate,endDate,cpcodes,streams,aggregation,limit,offset,filterParams,sortParams}
RTMP Ingest  
List RTMP Ingest dimensions GET /media-reports/v1/media-services-live/rtmp-ingest/dimensions
List RTMP Ingest metrics GET /media-reports/v1/media-services-live/rtmp-ingest/metrics
Get RTMP Ingest data POST /media-reports/v1/media-services-live/rtmp-ingest/data{?dimensions,metrics,startDate,endDate,cpcodes,limit,offset,aggregation,filterParams,sortParams,streams}
Get RTMP Ingest entry point switching information GET /media-reports/v1/media-services-live/rtmp-ingest/ep-switch/data{?dimensions,metrics,startDate,endDate,cpcodes,limit,offset,filterParams,sortParams,streams}

List HTTP Ingest dimensions

Retrieves all the dimensions available for HTTP Ingest (HLS/HDS/DASH).

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

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/v1/media-services-live/http-ingest/metrics

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/v1/media-services-live/http-ingest/data{?dimensions,metrics,startDate,endDate,cpcodes,limit,offset,aggregation,filterParams,sortParams,streams}

Sample: /media-reports/v1/media-services-live/http-ingest/data?dimensions=1%2C2%2C3&metrics=1%2C2%2C3&startDate=2014-03-22T15%3A30Z&endDate=2014-03-23T15%3A30Z&cpcodes=12345%2C67890&limit=300&offset=0&aggregation=1440&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D&streams=12345%2C67890

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/v1/media-services-live/http-ingest/ep-switch/data{?startDate,endDate,cpcodes,limit,offset,streams}

Sample: /media-reports/v1/media-services-live/http-ingest/ep-switch/data?startDate=2014-03-22T15%3A30Z&endDate=2014-03-23T15%3A30Z&cpcodes=12345%2C67890&limit=300&offset=0&streams=12345%2C67890

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/v1/media-services-live/http-ingest/origin-shield/dimensions

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/v1/media-services-live/http-ingest/origin-shield/metrics

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/v1/media-services-live/http-ingest/origin-shield/data{?dimensions,metrics,startDate,endDate,cpcodes,streams,aggregation,limit,offset,filterParams,sortParams}

Sample: /media-reports/v1/media-services-live/http-ingest/origin-shield/data?dimensions=1%2C2%2C3&metrics=1%2C2%2C3&startDate=2014-03-22T15%3A30Z&endDate=2014-03-23T15%3A30Z&cpcodes=12345%2C67890&streams=12345%2C67890&aggregation=1440&limit=300&offset=0&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

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/v1/media-services-live/rtmp-ingest/dimensions

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/v1/media-services-live/rtmp-ingest/metrics

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/v1/media-services-live/rtmp-ingest/data{?dimensions,metrics,startDate,endDate,cpcodes,limit,offset,aggregation,filterParams,sortParams,streams}

Sample: /media-reports/v1/media-services-live/rtmp-ingest/data?dimensions=1%2C2%2C3&metrics=1%2C2%2C3&startDate=2014-03-22T15%3A30Z&endDate=2014-03-23T15%3A30Z&cpcodes=12345%2C67890&limit=300&offset=0&aggregation=1440&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D&streams=12345%2C67890

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/v1/media-services-live/rtmp-ingest/ep-switch/data{?dimensions,metrics,startDate,endDate,cpcodes,limit,offset,filterParams,sortParams,streams}

Sample: /media-reports/v1/media-services-live/rtmp-ingest/ep-switch/data?dimensions=1%2C2%2C3&metrics=1%2C2%2C3&startDate=2014-03-22T15%3A30Z&endDate=2014-03-23T15%3A30Z&cpcodes=12345%2C67890&limit=300&offset=0&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D&streams=12345%2C67890

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.columns[] Provides context for each element listed within corresponding rows.
metaData Report.metaData 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