Tech Blog

How to use the “limit” and “ResumptionToken” in the “Retrieve Analytics report” API

In this blog we will describe how to use the “limit” and “ResumptionToken” parameters in the Retrieve Analytics Report API.

As a prerequisite for this blog it is highly recommended to first see How to use an API to retrieve an Alma Analytics report in 5 easy steps.

The “limit” and “ResumptionToken” parameters are explained in the documentation for the Retrieve Analytics Report API:

Let’s see how it works with a real live example:

If we have this example, then 25 rows are brought each time:

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FAlma University%2FReports%2FTitles%2FOverlap P and E for titles with LC classification code between H and HZ&limit=25&col_names=true&apikey=l8xx73f47f7b2a67469cb673f12a59cf4958

If we have this example, then 30 rows are brought each time:

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FAlma University%2FReports%2FTitles%2FOverlap P and E for titles with LC classification code between H and HZ&limit=30&col_names=true&apikey=l8xx73f47f7b2a67469cb673f12a59cf4958 

The amount of rows must be between 25 and 1000.  If the parameter will be less than 25 or more than 1000 then the following will be returned:

When a report is returned via the API and there are still more rows to display (there are more rows in the report than what was specified in the “limit” parameter) then the first time the API is run for the report there will be both

  1. This parameter:  <IsFinished>false</IsFinished>

  2. A ResumptionToken

For subsequent runs of the API on the same report the resumption token will not appear because the same resumption token can continue to be used for the rest of the report.

For example this:

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FAlma University%2FReports%2FTitles%2FOverlap P and E for titles with LC classification code between H and HZ&limit=25&col_names=true&apikey=l8xx73f47f7b2a67469cb673f12a59cf4958

Returns this

In order to see the next part of the report (after row 25 which was the limit in the API parameter) the ResumptionToken should be added as a parameter as follows:  Replace “path=full path of the report” with “path=Resumption token”

So in our example if we do this:

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FAlma University%2FReports%2FTitles%2FOverlap P and E for titles with LC classification code between H and HZ&limit=25&col_names=true&apikey=l8xx73f47f7b2a67469cb673f12a59cf4958

and get a resumption token of this:

63D89A8B92CEE544ED4DA8A0AF2D60B4637B4DB427EF7E48FCC1DA9AA24B055D79BA150C49A570A8214504E7D447D0A6677D3AD05EDC3CA7F06182E34E9D7A2F

Then the next call for the next part of the report will be:

https://api-eu.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?token=63D89A8B92CEE544ED4DA8A0AF2D60B4637B4DB427EF7E48FCC1DA9AA24B055D79BA150C49A570A8214504E7D447D0A6677D3AD05EDC3CA7F06182E34E9D7A2F&limit=25&col_names=true&apikey=l8xx73f47f7b2a67469cb673f12a59cf4958

If this call still returns “IsFinished=False” then send the same syntax again with the same resumption token and get the next part of the report.  Then keep sending it until “IsFinished=True” is returned:

This means that the entire report has been retrieved.

Leave a Reply