Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Report Pagination

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.

Panel
borderColor#000000
bgColor#FFD28C
borderWidth1
borderStylesolid
titleOn This Page
Table of Contents
maxLevel3
minLevel2

Report Pagination Required Fields

The feature requires that you include three fields in the body of your JSON request (for details, see the Example):

FieldTypeDescription
"offset"intThe row number that this report should start from.
"num_elements"intThe number of rows this report should return in total.
"orders"array of stringsThe order of the dimensions in the report.

Implementing Report Pagination

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. 

The "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.

The "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.  

Warning

The "orders" field should include an ordering for all dimensions included in your report. If you submit a request for a paginated report without the "orders" field or without all dimensions in the report, you may be missing rows of data or duplicating rows of data between the paged requests of your report.

How Many Rows Should You Retrieve at Once?

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. 

Example

Toggle Cloak
 Step 1. Create the paginated report JSON 
Cloak

This particular report will consist of two report requests: report_page_1.json and report_page_2.json. Note that the requests are identical except for the "offset" field, and that the "orders" field is required.

Toggle Cloak
 Step 2. Submit the requests
Cloak
Toggle Cloak
 Step 3. Check that both reports process
Cloak
Toggle Cloak
 Step 4. Download the finished reports
Cloak
Toggle Cloak
 Step 5. Check that row count matches total row count
Cloak

Related Topics