Working with reports
This section provides examples in curl and python of how to use the Reporting API to generate reports according to your preferences. You can define time window, granularity, metric type, and apply a range of filters.
Define your filters with the dimensions
object, and the dimension_filter_clauses
object which will contain an array of filter
objects.
Request metrics such as connections, time usage, and data usage with the metrics
object.
The example scripts in this section give a response in json format, however you can get responses in csv format with --header 'Accept: text/csv'
.
Time windows
Some of the reports below require you to specify the time window over which to run the report.
The time window is set with start_date_time
and end_date_time
. You can either specify actual times and dates, in the format YYYY-MM-DDTHH:mm:ss
, or request a set time block with LAST HOUR
, LAST DAY
, LAST WEEK
, LAST MONTH
or NOW
(returns the last 5 minutes).
If you are requesting a set time block, this must be configured in both start_date_time
and end_date_time
, for example:
"start_date_time": "LAST HOUR",
"end_date_time": "LAST HOUR",
You can also specify the data point frequency in your report with the granularity
parameter, which can be HOUR
or DAY
(default is HOUR
).
Bandwidth calculation
Bandwidth values are displayed in Mbps down to 2 decimal places. Values below 0.01 Mbps are rounded up or down accordingly, such that any value >=0.005 Mbps will be rounded up to 0.01 Mbps, and anything <0.005 Mbps will be rounded down to zero.
Average bandwidth
During a time period (as specified by the granularity
parameter), we count:
- Each second during which traffic was seen during the time period
- Total traffic seen during that time period.
To calculate the average bandwidth during the time period, we divide the total traffic seen during the time period (in bytes) by the number of seconds during which traffic was seen, and provide this value in megabits per second.
For example:
Time period (
granularity
) 1 hour
Traffic direction: UplinkDuring the hour we counted:
- 1750 seconds during which traffic was seen
- A total traffic of 25900000 bytes
Therefore the average bandwidth for that hour will be calculated thus:
25900000 / 1750 = 14800 bytes per second
14800 bytes per second = 0.1184 megabits per second.As we round up to 2 decimal places, the average uplink bandwidth for that hour will be shown as: 0.12 megabits per second
Maximum bandwidth
The specified time period (eg. 1 hour) is split into 5 minute windows, and we record the highest throughput per second seen during each 5 minute window. Once the time period has elapsed, the highest throughput recorded is displayed in Mbps as the maximum bandwidth for the time period.
Minimum bandwidth
The specified time period (eg. 1 hour) is split into 5 minute windows, and we record the lowest throughput per second seen during each 5 minute window. Once the time period has elapsed, the lowest throughput is displayed in Mbps as the minimum bandwidth for the time period. If there is a 5 minute window during which no traffic is seen, minimum bandwidth for the time period will be zero.