Report Pagination is a feature that allows API users to retrieve long-running reports that would otherwise time out before they complete processing. For more information about reporting API usage limits, see the Report Throttling section of the Report Service page.
Crafting a more granular report with fewer dimensions and metrics or pulling a report on a shorter timeframe is usually the best option for ensuring that a report does not time out. For tips on keeping your reports lean and focused, see the API Best Practices wiki page.
In some cases, however, it is not practical to change the dimensions, metrics or timeframe. Report pagination can help bridge the gap and allow you to retrieve a long-running report in smaller chunks.
The feature requires that you include three fields in the body of your JSON request (for details, see the Example):
|int||The row number that this report should start from.|
|int||The number of rows this report should return in total.|
|array of strings||The order of the dimensions in the report.|
If you have used the API's paging system for retrieving configuration objects from the API (as described in the Paging section of API Semantics), this feature should feel familiar.
"num_elements" field is used to specify how many rows are in each "page" of the report, and has no maximum value but should be tuned to a number that allows the report to process without timing out.
"offset" field should start at 0 and should increment in multiples of
"num_elements" until all rows of the report have been retrieved. When the report is retrieved, if there are
n-1 or fewer rows in the report (where
n equals the value in
"num_elements"), then you have requested all of the available rows in the report. If there are
n rows, then you should request another paginated report.
There is no maximum value on the
"num_elements" field, so you will want to tune this number against the time it takes to run a report in the specific member seat that you are retrieving. Most large reports can safely be retrieved with the
"num_elements" field set to a value between 1MM rows and 2MM rows, but you should test that value for your own report.
This particular report will consist of two report requests: