Reporting API v1

Overview

If you’re using Akamai’s intelligent platform to deliver your content,
you want to see how it’s performing. The 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. Some reports are available only to those who have purchased the
related product. 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, 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

To configure this API for the first time:

Create an API client in Akamai Control Center
for the Reporting API. Follow the steps in Get Started with
APIs
to learn how to configure credentials to access the API. Tokens appear
as customer hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

Available reports

The following table provides information for each type of report this
API generates, either available for all products, widely available
basic traffic reports, or enabled by the following products:

Provides volume of responses served by Akamai edge servers when you are using the Akamai Instant (Page Prefetching) behavior.

prefetchedgepfmetrics-by-time

Provides volume of cache hits served by Akamai edge servers for no-store or low-TTL objects when you are using the Akamai Instant (Page Prefetching) behavior.

prefetchoriginmetrics-by-time

Provides volume of responses served by your origin server when you are using the Akamai Instant (Page Prefetching) behavior.

Enabled by the IP Application Accelerator product

ipamapping-by-time

Provides data for DNS requests of any type that were made to process sessions associated with IPA traffic.

Enabled by the SaaS Provider Option product

saasappusers-by-cust

Provides the total number of users by SaaS customer for which traffic has been reported. You must identify a pattern for extracting customer ID and unique users using the SaaS Definitions Property Manager Behavior.

saascustusers-by-app

Provides the total number of users by SaaS application for which traffic has been reported. You must identify a pattern for extracting application ID and unique users using the SaaS Definitions Property Manager Behavior.

The data for DNS requests of any type that were made to process sessions associated with IPA traffic.

Gather data to execute the report

Each report allows a different range of request options, so first you
need to gather all the information you’ll need to execute it:

Gather a list of CP codes for which you want to report data.

Run the List report types operation. Optionally
specify showDeprecated=false to narrow the results to the latest
available version. Set showUnavailable=false to omit any reports
that your API client’s identity can’t execute.

If you want to view other reports not available under your
product, set showUnavailable=true, but note that you can’t
execute any report unless it is marked as available. While you
can execute many reports under any Akamai product, some require
specific sets of products to enable them. If a report is
unexpectedly not available, make sure you’re executing the
report with access to any of the requiredProducts specified.
Also make sure the API client identity has any of the permissions
specified in requiredRoles.

Optionally store any object from the List report
types operation’s response array and store its name
and version values. Otherwise use those values to run the Get a
report type operation, storing its response
object. The ReportType object includes most of the
data you need to execute the report.

From the ReportType object’s metrics array, store
an array of each metric name you want to include in the report. The
accompanying fullDescription provides documentation for each metric.

From the filters array, store an object mapping of each filter
name you want to refine results with. Make sure to include any
filters that are required. The accompanying fullDescription
provides documentation for each filter.

For each filter name key you include in the map, the value needs
to be an array. If the filter type is int or string, specify
whatever set of values you want to refine the report. If the type is
enum, then for each object in values, include any available
value in the array. An accompanying fullDescription may clarify
its use.

The intervals array specifies a set of duration values, available
for each report, to aggregate each row of data. Select a value to
later pass in as the interval query parameter.

Specify an overall time span for the entire report as start and
end parameter values. But note that there may be a maxLimit cap
on the number of data rows in each report. If the interval value is
too brief, the report may fail to execute.

Execute the report

The API provides two operations that allow you to execute reports in
slightly different ways:

The Generate a report POST operation allows you to
submit a request with a Query JSON object that specifies the
report’s criteria.

The Get a cacheable report GET operation specifies the
same data as query parameters, allowing you to take advantage of a
five minute cache to refresh data more quickly. However, overly long
URLs may fail to execute, in which case use you can run the POST
operation instead.

Specify an objectIds query parameter with the set of CP codes you
want to report on, separated with commas. Otherwise instead you can
specify an allObjectIds query parameter to widen the scope of the
report. Doing so may also shorten the URL.

Specify a metrics query parameter, with the set of metric name
values you gathered earlier, separated with commas.

Specify a filters query parameter, with the set of filter name
values you gathered earlier, followed by = and the corresponding
value. Separate each name/value pair with commas. To represent more
than one value, repeat the filter name. For example, this is how
filters would appear prior to URL-encoding:
filters=ip_version=ipv4,ip_version=ipv6,traffic_type=standard_secure.

To get CSV data instead of JSON:

When making either the POST or GET request described above, set the
Accept header to text/csv, application/problem+json for CSV output
with JSON error messaging.

Example: Get a report for Origin Performance

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 data 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 2, as
listed in Available reports.

Example: Generate a report on Origin Performance

To generate a report on Origin Performance with POST, 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.

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 several CP codes. The request specifies a set
of metrics:

The response’s metadata section reflects context about the data you
requested, based on both the supplied set of query parameters and 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:

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:

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.

Resources

This section provides details on the Reporting API’s operations and
parameters.

Get a cacheable report

Produce a report in either JSON or CSV
format for a specific version of a type of report. While
functionally identical to Generate a report, this
alternative GET operation specifies all request data as query
parameters. Once initially generated, the API caches
corresponding Report responses for quicker access.

Specifies the end of the reported period as an ISO–8601 timestamp with optional time zone. The report excludes any data that matches the end value’s timestamp.

interval

Enumeration

DAY

The duration of each data record, either FIVE_MINUTES, HOUR, DAY, WEEK, or MONTH. Support for specific interval values may vary for each report type.

objectType

Enumeration

cpcode

Specifies the type of object you want to report on. The only currently available option is to report by cpcode.

start

String

2016-07-01T00:00:00Z

Specifies the start of the reported period as an ISO–8601 timestamp with optional time zone.

Optional query parameters

allObjectIds

Boolean

true

As an alternative to objectIds, enabling this generates a report that includes all IDs available for the specified objectType. This parameter is ignored if the request also specifies a set of objectIds.

filters

String

ip_version=ipv4,ip_version=ipv6, traffic_type=standard_secure

Specifies criteria to filter the report’s data. The set of available filters depends on the type of report. Separate each filter name and value with an equals (=) character, and separate various name/value pairs with commas (,). To specify more than one filter value, repeat the filter name. See the accompanying example for guidance. URL-encode the entire value in the GET request.

metrics

String

top_urls,browser_hits, edgres_hits_success

Specifies a comma-separated list of metrics to include in the report, otherwise all metrics if omitted. The set of available metrics depends on the type of report.

objectIds

String

55232,23433,32433

As an alternative to allObjectIds, specifies the set of unique IDs for the given objectType you want to report on, formatted as a comma-delimited list.

Generate a report

Produce a report in either JSON or CSV format
for a specific version of a type of report.
Query parameters specify the range of data and the aggregation
interval for each record. While functionally identical to
Get a cacheable report,
this POST operation specifies a Query request object
for a corresponding Report response, which the API
does not cache.

Data

This API framework specifies a single Query schema
whose set of supported metrics and filters varies for each
version of a report type. In addition to a fixed set of
Report schema members, the response’s data
object array reflects back the set of requested metrics.

Note that the list of objectIds identified in your query must be unique.

Collects Key Performance Indicator data. The name of each KPI metric serves as the object key.

Report.data[]: Array of objects representing data rows suitable for aggregation. The value of the groupBy array always appears as a key for each row to indicate by which metric it is grouped and sorted.

startdatetime

String

&cir;

For certain time series reports, an ISO 8601 timestamp marking the start of each record.

timestamp

String

&cir;

For certain time series reports, an ISO 8601 timestamp marking the start of each record.

Report.metadata: Collects context about the requested data set based on the request’s parameters and contents of the Query object, and supplies presentational information for use in report output.

availableDataEnds

String, Null

&check;

If data has not been finalized, this ISO 8601 timestamp indicates for when data is no longer available. Otherwise the value is null for finalized data.

HTTP status codes

Invalid report request. For example, this error occurs if you form a filter value incorrectly, forget a required filter, or use a filter or metric not supported by a type of report. The associated error message instructs you further.

Access is forbidden, for example, when you don’t have access to one or more objects, like CP codes, for which you tried to retrieve data. If needed, talk to your local administrator to adjust access. See Get Started with APIs for more information.