The following shows how to generate the delivery/traffic/current
report with the Generate a report POST operation of the Reporting API v2. See also other available reports.
Report definition
Provides Akamai CDN traffic report data.
The report doesn't include data for EdgeKV product.
Data available for: 92 days
Available metrics
Metric name | Description | Configuration |
---|---|---|
edgeBytesSum | The total volume of edge traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
edgeHitsSum | The total number of edge requests for given objects and filters. | type: LONG, filterable: true, mandatory: false |
edgeResponseBytesSum | Sum of response bytes of edge traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
edgeRequestBytesSum | Sum of request bytes of edge traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
originBytesSum | The total volume of origin traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
originHitsSum | The total number of origin requests for given objects and filters. | type: LONG, filterable: true, mandatory: false |
originResponseBytesSum | Sum of response bytes of origin traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
originRequestBytesSum | Sum of request bytes of origin traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
midgressHitsSum | All hits with all response codes delivered from Akamai Tiered Distribution network, that is bytes served from the Akamai Tiered Distribution infrastructure to edge servers. | type: LONG, filterable: true, mandatory: false |
midgressBytesSum | The total volume of midgress traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
midgressResponseBytesSum | Sum of response bytes of midgress traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
midgressRequestBytesSum | Sum of request bytes of midgress traffic for given objects and filters. | type: LONG, filterable: true, mandatory: false |
offloadedHitsPercentage | The number of hits that Akamai served as a percentage of total hits served for given objects and filters. | type: DOUBLE, filterable: true, mandatory: false |
offloadedBytesPercentage | The volume that Akamai served as a percentage of total volume served for given objects and filters. | type: DOUBLE, filterable: true, mandatory: false |
offloadedRequestBytesPercentage | The request volume that Akamai served as a percentage of total volume served for given objects and filters. | type: DOUBLE, filterable: true, mandatory: false |
offloadedResponseBytesPercentage | The response volume that Akamai served as a percentage of total volume served for given objects and filters. | type: DOUBLE, filterable: true, mandatory: false |
Available dimensions
Dimension name | Description | Configuration |
---|---|---|
time5minutes | Datapoint timestamp for 5 minutes granularity. | type: TIMESTAMP_SEC, filterable: false, mandatory: false, filterType: TEXT, authorizable: false |
time1hour | Datapoint timestamp for 1 hour granularity. | type: TIMESTAMP_SEC, filterable: false, mandatory: false, filterType: TEXT, authorizable: false |
time1day | Datapoint timestamp for 1 day granularity. | type: TIMESTAMP_SEC, filterable: false, mandatory: false, filterType: TEXT, authorizable: false |
cpcode | Content provider (CP) code for which you want data included. | type: LONG, filterable: true, mandatory: false, filterType: TEXT, authorizable: true |
hostname | Hostname for which you want data included. | type: STRING, filterable: true, mandatory: false, filterType: TEXT, authorizable: false |
responseCode | An HTTP response status code. For example, 201. | type: LONG, filterable: true, mandatory: false, filterType: TEXT, authorizable: false |
responseClass | An HTTP response status code class. For example, 2xx. | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: 0xx, 1xx, 2xx, 3xx ,4xx, 5xx, 6xx authorizable: false |
responseStatus | An HTTP response status, either success or error. | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: success ,error authorizable: false |
httpMethod | An HTTP method for which you want data included, either put_post or get_head . | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: get_head , put_post authorizable: false |
deliveryType | Distinguishes secure from non-secure traffic. | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: non_secure , secure authorizable: false |
cacheability | Indicates whether the content is storable. | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: cacheable ,non_cacheable authorizable: false |
ipVersion | IP format for which you want data included, either ipv4 or ipv6 . | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: ipv4 , ipv6 authorizable: false |
httpProtocol | HTTP version for which you want data included. For example, http3 . | type: STRING, filterable: true, mandatory: false, filterType: ENUM, filterEnumValues: http1.1 , https1.1 , http2 , http3 authorizable: false |
arlId | Unique identifier of the Akamai Resource Locator. | type: LONG, filterable: true, mandatory: false, filterType: TEXT, authorizable: false |
Generate a report
Use the Generate a report POST operation to execute a report.
Follow the API workflows to:
POST request sample
POST /reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_1_WEEK
Available time ranges
For this report, you can use these predefined ranges in the timeRange
query parameter:
LAST_15_MINUTES
LAST_30_MINUTES
LAST_1_HOUR
LAST_3_HOURS
LAST_6_HOURS
LAST_12_HOURS
LAST_1_DAY
LAST_2_DAYS
LAST_1_WEEK
LAST_30_DAYS
LAST_90_DAYS
Supported filters
This report supports filtering by dimensions and metrics.
You can filter by each dimension or metric that is labeled as filterable: true
in the report options. See how to use filters.
Request body example
{
"dimensions": [
"cpcode",
"ipVersion",
"httpMethod"
],
"metrics": [
"edgeBytesSum",
"edgeHitsSum",
"edgeResponseBytesSum",
"edgeRequestBytesSum",
"originBytesSum",
"originHitsSum",
"midgressBytesSum",
"midgressHitsSum",
"offloadedHitsPercentage",
"offloadedBytesPercentage"
],
"filters": [
{
"dimensionName": "cpcode",
"operator": "IN_LIST",
"expressions": [
1849,2084,2577,3004
]
},
{
"dimensionName": "ipVersion",
"operator": "IN_LIST",
"expressions": [
"ipv4"
]
},
{
"metricName": "edgeHitsSum",
"operator": "GREATER_THAN",
"expression": 1
}
],
"sortBys": [
{
"name": "cpcode",
"sortOrder": "DESCENDING"
}
],
"limit": 1000
}
Default values
These default values apply to all requests, meaning they are used unless you specify otherwise.
-
Time range. Short relative range of 5 minutes configured in the following way, to always return a single 5 minute data point.
-
start
= now - 19 minutes -
end
= now - 9 minutes 1 secondExample: If now is 10:19:00, the default time range is:
start
= 10:00:00
end
= 10:09:59
The report time range is 10:00:00-10:05:00
-
-
Metrics:
edgeHitsSum
edgeBytesSum
-
Dimensions:
hostname
responseCode
-
Filters:
cpcode
. You can use all CP codes to which you are authorized in Control Center. If you don't specify any CP codes in your request, the report shows data for all your available CP codes.
-
SortBys:
hostname, ASCENDING
edgeHitsSum, DESCENDING
Limits
Each report has some configured limits. If your request has values that exceed the limits, it results in a HTTP 400 Bad Request response. This report has the following limits:
Setting | Limit |
---|---|
Maximum number of dimensions | 4 |
Maximum time range | 92 days |
Maximum retention of historic data | 92 days |
Maximum length of value for TEXT filters | 100 |
Maximum number of data points returned | 50000 |
Rate limiting
This report uses both cost-based and hit-based rate limiting. For the hit-based rate limiting, the limit for an account is 10 requests per minute.
In the asynchronous flow, you can have 3 queued POST requests at the same time.
Read more about the rate limiting.
Calculate advanced metrics
The Reporting API v2 gives you insight into basic hits, bytes, and offload metrics, which you can use to calculate more advanced metrics. Examples:
-
hits/sec
. Divide the number of hits by the number of seconds for a given time dimension. For example, 300 for thetime5minutes
dimension. -
bits/sec
. Multiply the number of bytes by 8 and divide by the number of seconds for a given time dimension. For example, 300 for thetime5minutes
dimension.
Get report options
To get the report metadata through the API, run the Get report options operation.
GET /reporting-api/v2/reports/delivery/traffic/current
The response shows the list of available metrics and dimensions, the default values, and configured limits.
{
"name": "CDN traffic report data",
"description": "Provides CDN traffic report data.",
"status": "PUBLISHED",
"metrics": [
{
"name": "edgeBytesSum",
"description": "The total volume of edge traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "edgeHitsSum",
"description": "The total number of edge requests for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "edgeResponseBytesSum",
"description": "Sum of response bytes of edge traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "edgeRequestBytesSum",
"description": "Sum of request bytes of edge traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "originBytesSum",
"description": "The total volume of origin traffic for given objects and filters",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "originHitsSum",
"description": "The total number of origin requests for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "originResponseBytesSum",
"description": "Sum of response bytes of origin traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "originRequestBytesSum",
"description": "Sum of request bytes of origin traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "midgressBytesSum",
"description": "The total volume of midgress traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "midgressHitsSum",
"description": "All hits with all response codes delivered from the Tiered Distribution network, that is bytes served from the Tiered Distribution infrastructure to edge servers.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "midgressResponseBytesSum",
"description": "Sum of response bytes of midgress traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "midgressRequestBytesSum",
"description": "Sum of request bytes of midgress traffic for given objects and filters.",
"type": "LONG",
"filterable": true,
"mandatory": false
},
{
"name": "offloadedHitsPercentage",
"description": "The number of hits served from the CDN as a percentage of total hits served for given objects and filters.",
"type": "DOUBLE",
"filterable": true,
"mandatory": false
},
{
"name": "offloadedBytesPercentage",
"description": "The volume served from the CDN as a percentage of total volume served for given objects and filters.",
"type": "DOUBLE",
"filterable": true,
"mandatory": false
},
{
"name": "offloadedRequestBytesPercentage",
"description": "The request volume served from the CDN as a percentage of total volume served for given objects and filters.",
"type": "DOUBLE",
"filterable": true,
"mandatory": false
},
{
"name": "offloadedResponseBytesPercentage",
"description": "The response volume served from the CDN as a percentage of total volume served for given objects and filters.",
"type": "DOUBLE",
"filterable": true,
"mandatory": false
}
],
"dimensions": [
{
"name": "time5minutes",
"description": "Datapoint timestamp for 5 minutes granularity.",
"type": "TIMESTAMP_SEC",
"filterable": false,
"mandatory": false,
"filterType": "TEXT",
"authorizable": false
},
{
"name": "time1hour",
"description": "Datapoint timestamp for 1 hour granularity.",
"type": "TIMESTAMP_SEC",
"filterable": false,
"mandatory": false,
"filterType": "TEXT",
"authorizable": false
},
{
"name": "time1day",
"description": "Datapoint timestamp for 1 day granularity.",
"type": "TIMESTAMP_SEC",
"filterable": false,
"mandatory": false,
"filterType": "TEXT",
"authorizable": false
},
{
"name": "cpcode",
"description": "Content provider (CP) code for which you want data included.",
"type": "LONG",
"filterable": true,
"mandatory": false,
"filterType": "TEXT",
"authorizable": true
},
{
"name": "hostname",
"description": "Hostname for which you want data included.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "TEXT",
"authorizable": false
},
{
"name": "responseCode",
"description": "An HTTP response status code. For example, 201.",
"type": "LONG",
"filterable": true,
"mandatory": false,
"filterType": "TEXT",
"authorizable": false
},
{
"name": "responseClass",
"description": "An HTTP response status code class. For example, 2xx.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"0xx",
"1xx",
"2xx",
"3xx",
"4xx",
"5xx",
"6xx"
],
"authorizable": false
},
{
"name": "responseStatus",
"description": "An HTTP response status, either success or error.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"error",
"success"
],
"authorizable": false
},
{
"name": "httpMethod",
"description": "An HTTP method for which you want data included, either put_post or get_head.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"get_head",
"put_post"
],
"authorizable": false
},
{
"name": "deliveryType",
"description": "Distinguishes secure from non-secure traffic.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"non_secure",
"secure"
],
"authorizable": false
},
{
"name": "cacheability",
"description": "Indicates whether the content is storable.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"cacheable",
"non_cacheable"
],
"authorizable": false
},
{
"name": "ipVersion",
"description": "IP format for which you want data included, either ipv4 or ipv6.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"ipv4",
"ipv6"
],
"authorizable": false
},
{
"name": "httpProtocol",
"description": "HTTP version for which you want data included. For example, http3.",
"type": "STRING",
"filterable": true,
"mandatory": false,
"filterType": "ENUM",
"filterEnumValues": [
"http1.1",
"https1.1",
"http2",
"http3"
],
"authorizable": false
},
{
"name": "arlId",
"description": "Unique identifier of the resource locator.",
"type": "LONG",
"filterable": true,
"mandatory": false,
"filterType": "TEXT",
"authorizable": false
}
],
"predefinedTimeRanges": [
"LAST_15_MINUTES",
"LAST_30_MINUTES",
"LAST_1_HOUR",
"LAST_3_HOURS",
"LAST_6_HOURS",
"LAST_12_HOURS",
"LAST_1_DAY",
"LAST_2_DAYS",
"LAST_1_WEEK",
"LAST_30_DAYS",
"LAST_90_DAYS"
],
"defaults": {
"defaultTimeRange": {
"start": "now - 19 min",
"end": "now - 9 min 1 sec"
},
"defaultMetrics": [
"edgeHitsSum",
"edgeBytesSum"
],
"defaultDimensions": [
"hostname",
"responseCode"
],
"defaultSortBys": [
{
"name": "hostname",
"sortOrder": "ASCENDING"
},
{
"name": "edgeHitsSum",
"sortOrder": "DESCENDING"
}
]
},
"limits": {
"maxDimensions": 4,
"maxDateRangeInDays": 92,
"maxRetentionInDays": 92,
"textFilterMaxLength": 100,
"dataPointsLimit": 50000
},
"links": [
{
"rel": "self",
"href": "/reporting-api/v2/reports/delivery/traffic/current",
"describedBy": "/reporting-api/v2/reports/schema",
"allow": [
"GET"
]
},
{
"rel": "data",
"href": "/reporting-api/v2/reports/delivery/traffic/current/data",
"allow": [
"POST"
]
}
]
}
Key use cases and best practices
Monitoring
In this use case, you use the hostname data for monitoring your digital properties with low latency. For example, you want to track the number of hits and bytes delivered for different hostnames along with the status code. This can help your operational personnel monitor the health of the system and monitor side effects due to configuration changes.
Best practices
For the monitoring use case, use the LAST_15_MINUTES
time range to retrieve data. To get data at 5 minute granularity, you can use LAST_15_MINUTES
, LAST_30_MINUTES
, LAST_1_HOUR
, or LAST_3_HOURS
time ranges to fetch updated data points. Note that the hostname reporting systems aim to have an SLO of 15 minutes for 95% data completion. You can consider data finalized after 1 hour as <1% data is updated after this time.
Usage samples
-
Monitoring per CP code:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_15_MINUTES
- Request body:
{ "dimensions": [ "cpcode" ], "metrics": [ "edgeHitsSum", "edgeBytesSum" ], "sortBys": [ { "name": "edgeHitsSum", "sortOrder": "DESCENDING" } ] }
- URL:
-
Monitoring per hostname:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_15_MINUTES
- Request body:
{ "dimensions": [ "hostname" ], "metrics": [ "edgeHitsSum", "edgeBytesSum" ], "sortBys": [ { "name": "edgeHitsSum", "sortOrder": "DESCENDING" } ] }
- URL:
-
Errors monitoring per hostname:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_15_MINUTES
- Request body:
{ "dimensions": [ "hostname", "responseClass" ], "metrics": [ "edgeHitsSum", "edgeBytesSum" ], "sortBys": [ { "name": "edgeHitsSum", "sortOrder": "DESCENDING" } ] }
- URL:
-
Origin traffic monitoring per response code:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_15_MINUTES
- Request body:
{ "dimensions": [ "responseCode" ], "metrics": [ "originHitsSum", "originBytesSum" ], "sortBys": [ { "name": "originHitsSum", "sortOrder": "DESCENDING" } ] }
- URL:
Long term trend analysis
In this use case, you analyze traffic data along dimensions such as time, hostname, status code, or HTTP method. You analyze the data across multiple days, at one hour or one day granularity.
Best practices
For a long or mid term trend analysis , you can make a single API call with the required set of dimensions, metrics, and filters. Select the data granularity of 1 hour or 1 day for a date range older than 1 hour, when the data is considered 99% finalized. Don't select a large set of dimensions as it'd render the trend analysis intractable. Instead, choose one or two dimensions you want to analyze. On any dimension, you can specify filtering conditions. Alternatively, you may find using Control Center UI more useful.
Usage samples
-
Trend analysis of HTTP status codes over time for a given list of CP codes in the last week:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_1_WEEK
- Request body:
{ "dimensions": [ "time1hour", "responseCode" ], "metrics": [ "edgeHitsSum" ], "filters": [ { "dimensionName": "cpcode", "operator": "IN_LIST", "expressions": [ "12345", "44444", "55555" ] } ], "sortBys": [ { "name": "time1hour", "sortOrder": "ASCENDING" } ] }
- URL:
-
Trend analysis per hostname:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_1_WEEK
- Request body:
{ "dimensions": [ "hostname", "time1hour" ], "metrics": [ "edgeHitsSum" ], "sortBys": [ { "name": "time1hour", "sortOrder": "ASCENDING" } ] }
- URL:
-
Trend analysis per CP code:
- URL:
/reporting-api/v2/reports/delivery/traffic/current/data?timeRange=LAST_1_WEEK
- Request body:
{ "dimensions": [ "cpcode", "time1hour" ], "metrics": [ "edgeHitsSum" ], "sortBys": [ { "name": "time1hour", "sortOrder": "ASCENDING" } ] }
- URL:
Data scraping
In this use case, you scrape the data stored in Akamai systems to join it with your own data sets for further analysis. You use the Akamai APIs to fetch the data at regular intervals. You can wait for the data to be complete before scraping it. To fetch entire datasets via the API v2, you can use the asynchronous API.
Best practices
For the data scraping use case, you can use a single API call to retrieve data with all dimensions, including time, and metrics after two hours, when the data is considered finalized. You can use the pagination feature as well to retrieve the data.
Anomaly detection
In this use case, you want to identify the characteristics of traffic that exhibit an unexpected trend. This use case is an extension of a long term trend analysis , in which you fetch the data repeatedly with different filter values. Usually, such data fetching happens through a UI widget and the rate of queries is low due to the fetch-analyze-refetch cycle. Alternatively, you could implement a data scraping strategy and analyze the data using automated systems at your end.
Alerting
In this use case, you fetch data at regular time intervals to detect alert conditions.