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
Request metrics such as connections, time usage, and data usage with the
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'.
Some of the reports below require you to specify the time window over which to run the report.
The time window is set with
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 MONTH or
NOW (returns the last 5 minutes).
If you are requesting a set time block, this must be configured in both
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
DAY (default is
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.
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.
Time period (
granularity) 1 hour
Traffic direction: Uplink
During 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
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.
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.