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 nameDescriptionConfiguration
edgeBytesSumThe total volume of edge traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
edgeHitsSumThe total number of edge requests for given objects and filters.type: LONG,
filterable: true,
mandatory: false
edgeResponseBytesSumSum of response bytes of edge traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
edgeRequestBytesSumSum of request bytes of edge traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
originBytesSumThe total volume of origin traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
originHitsSumThe total number of origin requests for given objects and filters.type: LONG,
filterable: true,
mandatory: false
originResponseBytesSumSum of response bytes of origin traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
originRequestBytesSumSum of request bytes of origin traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
midgressHitsSumAll 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
midgressBytesSumThe total volume of midgress traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
midgressResponseBytesSumSum of response bytes of midgress traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
midgressRequestBytesSumSum of request bytes of midgress traffic for given objects and filters.type: LONG,
filterable: true,
mandatory: false
offloadedHitsPercentageThe number of hits that ​Akamai​ served as a percentage of total hits served for given objects and filters.type: DOUBLE,
filterable: true,
mandatory: false
offloadedBytesPercentageThe volume that ​Akamai​ served as a percentage of total volume served for given objects and filters.type: DOUBLE,
filterable: true,
mandatory: false
offloadedRequestBytesPercentageThe request volume that ​Akamai​ served as a percentage of total volume served for given objects and filters.type: DOUBLE,
filterable: true,
mandatory: false
offloadedResponseBytesPercentageThe 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 nameDescriptionConfiguration
time5minutesDatapoint timestamp for 5 minutes granularity.type: TIMESTAMP_SEC,
filterable: false,
mandatory: false,
filterType: TEXT,
authorizable: false
time1hourDatapoint timestamp for 1 hour granularity.type: TIMESTAMP_SEC,
filterable: false,
mandatory: false,
filterType: TEXT,
authorizable: false
time1dayDatapoint timestamp for 1 day granularity.type: TIMESTAMP_SEC,
filterable: false,
mandatory: false,
filterType: TEXT,
authorizable: false
cpcodeContent provider (CP) code for which you want data included.type: LONG,
filterable: true,
mandatory: false,
filterType: TEXT,
authorizable: true
hostnameHostname for which you want data included.type: STRING,
filterable: true,
mandatory: false,
filterType: TEXT,
authorizable: false
responseCodeAn HTTP response status code. For example, 201.type: LONG,
filterable: true,
mandatory: false,
filterType: TEXT,
authorizable: false
responseClassAn 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
responseStatusAn HTTP response status, either success or error.type: STRING,
filterable: true,
mandatory: false,
filterType: ENUM,
filterEnumValues: success,error
authorizable: false
httpMethodAn 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
deliveryTypeDistinguishes secure from non-secure traffic.type: STRING,
filterable: true,
mandatory: false,
filterType: ENUM,
filterEnumValues:
non_secure, secure
authorizable: false
cacheabilityIndicates whether the content is storable.type: STRING,
filterable: true,
mandatory: false,
filterType: ENUM,
filterEnumValues:
cacheable,
non_cacheable
authorizable: false
ipVersionIP format for which you want data included, either ipv4 or ipv6.type: STRING,
filterable: true,
mandatory: false,
filterType: ENUM,
filterEnumValues:
ipv4, ipv6
authorizable: false
httpProtocolHTTP 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
arlIdUnique 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 second

      Example: 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:

SettingLimit
Maximum number of dimensions4
Maximum time range92 days
Maximum retention of historic data92 days
Maximum length of value for TEXT filters100
Maximum number of data points returned50000

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 the time5minutes 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 the time5minutes 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"
          }
        ]
      }
      
  • 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"
            }
          ]
        }
      
  • 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"
          }
        ]
      }
      
  • 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"
          }
        ]
      }
      

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"
            }
          ]
        }
      
  • 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"
          }
        ]
      }
      
  • 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"
          }
        ]
      }
      

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.