The Reporting API

If you’re using Akamai’s intelligent platform to deliver your content, you want to see how it’s performing. The beta Reporting API provides a wide range of reports, with new reports added periodically, and allows you to retrieve data in a range of intervals, from five minutes to monthly, depending on the time period and type of data you want to view. Support for specific intervals, filters, and metrics may vary by report type.

Who Should Use This API

Use the Reporting API if you want to analyze data about your business on the web. You can use the data to monitor traffic, analyze patterns for troubleshooting, find out how popular specific content is, compile information to inform others, or forecast capacity. These reports’ key performance indicators highlight the value of using Akamai to deliver and secure your content.

In addition to general traffic information including hits, bytes, traffic offloaded onto the Akamai network, and URL data, you can access additional data most relevant to the set of Akamai services you use.

Getting Started

Before using the API for the first time:

  • Review Get Started on tools that Akamai provides for all its APIs.

  • Review Authorize Your Client to create your API access credentials and authorizations. As detailed in the API Identity Model section, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • Review the Authorize Your Client section to make sure the identity under which you provision the API can access its full range of functionality. The API limits the scope of the returned data by the user’s contract and account, its permissions, and access to the business objects (for example, a CP code) that are associated with the user and account. Use the Identity Management application to expand access if necessary, or the Identity Management API as a programmatic alternative.

Reporting API Workflow

In this API framework, you use a single Generate a Report operation to produce reports for various types of data to which you have access:

  1. Pick the reportName you want from Available Reports.

  2. Each reportName supports different versions, for which you may vary the reportVersion. The latest version for each report is also listed in Available Reports.

  3. Specify the start and end range as query parameters, and the interval for the data granularity.

  4. Prepare a Query object for the POST request that specifies the set of objectIds you want to report on. The objectType identifies what each object represents, for example, a cpcode.

  5. Optionally specify a subset of metrics within the Query request, or corresponding filters to refine the results. Otherwise all metrics available for the version of the report type generate unfiltered.

  6. The response’s Report object reflects back the set of requested metrics in each row of data. It also reflects back details about the request context as metadata.

  7. Set the Accept header to application/json for JSON output, or text/csv, application/problem+json for CSV output with JSON error messaging.

Report on Origin Performance

Origin Performance reporting provides insight into performance characteristics observed by Akamai edge servers when making requests to your origin servers.

Metrics are collected as a request travels from the edge servers to your origin, and the associated response travels from your origin to the edge servers. The request/response represents an exchange between the edge servers and your origin.

This reporting API provides traffic data for those exchanges. You can filter this performance date by whether or not the content is cacheable, and what HTTP response codes were returned by your origin.

The most recent version of the Origin Performance report is listed in Available Reports, the most recent version for each report is 1. Prepare a base URL such as this:

/reporting-api/v1/reports/opresponses-by-time/versions/2/report-data

Additional query parameters set the range of the report and the interval each record represents. For example, you can specify an interval of a DAY. The example below shows how you would generate data over a range of a week. Since the report aggregates data per customer, data for each customer appears in separate records.

/reporting-api/v1/reports/opresponses-by-time/versions/2/report-data?interval=DAY&start=2017-05-10T00:00:00Z&end=2017-05-17T00:00:00Z

To prepare the Query object for the POST request, you need a set of objectIds to report on, which for this type of report is a CP code. As listed in Available Reports, you reflect that as an objectType of cpcode.

This sample request shows how you would specify an Origin Performance report provisioned under the 33190 CP code. The request specifies a set of metrics:

{
  "objectType": "cpcode",
  "objectIds": [
        "536194", "536198", "539651", "539798", "539987"
  ],
  "filters": {},
  "metrics": [
    "originResponsesTotal",
    "originResponses",
    "originResponsesSlope",
    "minOriginResponseTime",
    "avgResponseTime",
    "maxOriginResponseTime"
  ]
}

The response’s metadata section reflects context about the data you requested, based on both the supplied set of query parameters and the the Query request object. The groupBy indicates that the data is by start date (startdatetime).

Response data represents your full set of requested metrics, along with the objectId for each record. The following shows a small example of response output:

{
  "metadata": {
    "name": "opresponses-by-time",
    "version": "2",
    "groupBy": [
      "startdatetime"
    ],
    "interval": "FIVE_MINUTES",
    "start": "2017-09-18T04:00:00Z",
    "end": "2017-09-18T04:15:00Z",
    "availableDataEnds": "2017-09-18T04:10:00Z",
    "suggestedRetryTime": "2017-09-18T18:32:27.911Z",
    "rowCount": 3,
    "filters": [],
    "columns": [
      {
        "name": "originResponsesSlope",
        "label": "Origin Responses/Sec Slope"
      },
      {
        "name": "avgResponseTime",
        "label": "Average Origin Response Time "
      },
      {
        "name": "maxOriginResponseTime",
        "label": "Maximum Origin Response Time "
      },
      {
        "name": "minOriginResponseTime",
        "label": "Minimum Origin Response Time"
      },
      {
        "name": "originResponsesTotal",
        "label": "Origin Responses Total"
      },
      {
        "name": "originResponses",
        "label": "Origin Responses/Sec"
      }
    ],
    "objectType": "cpcode",
    "objectIds": [
        "536194", "536198", "539651", "539798", "539987"
    ]
  },
  "data": [
    {
      "minOriginResponseTime": "0",
      "maxOriginResponseTime": "2367",
      "avgResponseTime": "96.683065",
      "originResponses": "11.52",
      "startdatetime": "2017-09-18T04:00:00Z"
    },
    {
      "minOriginResponseTime": "2",
      "maxOriginResponseTime": "1293",
      "avgResponseTime": "61.359237",
      "originResponses": "14.50666666666667",
      "startdatetime": "2017-09-18T04:05:00Z"
    },
    {
      "minOriginResponseTime": "2",
      "maxOriginResponseTime": "2501",
      "avgResponseTime": "64.462784",
      "originResponses": "11.54",
      "startdatetime": "2017-09-18T04:10:00Z"
    }
  ],
  "summaryStatistics": {
    "originResponsesTotal": {
      "value": "11270",
      "details": {}
    },
    "originResponsesSlope": {
      "value": "0.0100000000000",
      "details": {}
    }
  }
}

Optionally specify a set of filters to refine the data, based on this report type. You can also vary the set of requested metrics as needed. This sample requests data only for minimum and maximum origin response times, and applies filters to consider only non-cacheable content requests:

{
    "objectType": "cpcode",
    "objectIds": [
        "536194", "536198", "539651", "539798", "539987"
    ],
    "metrics": [ "minOriginResponseTime", "maxOriginResponseTime" ],
    "filters": {
        "ca": [ "non-cacheable" ]
    }
}

NOTE: Response data aggregates according to the interval you specify. Some report types return aggregate data and some return time series data, which includes a timestamp for each interval in the response.


Last modified: 10/23/2017