Limits & Continuation Tokens

Fetching Records in Bulk

LiquidPlanner supports bulk fetching of records via different API methods (including /items, /logged-time-entries, etc). The data returned is sorted in ascending order by LiquidPlanner ID. We have pagination in place to help with retrieving a large volume of data in small chunks.

Pagination allows you to designate the number of records to retrieve at a time by setting a limit. When the total number of records exceeds the limit, a Continuation Token is provided in the response. Use the token to retrieve the next set of records. If you don't set a limit, Pagination kicks in automatically and provides a Continuation Token when the total number of records exceeds 500.

Parameters to Control Pagination

Please note that the parameters to control Pagination are case sensitive.

limit: Enter the number of records that you want to retrieve at a time. If you don’t specify a limit, then the system applies a 500 record limit by default.

recordLimit: is the number of records that will be retrieved based on the limit you set. If you did not enter a limit, the system applies 500 which is the maximum that can be requested at a time.

recordCount: displays the number of records retrieved in the current response.

continuationToken: This contains the LiquidPlanner ID Number of the last item retrieved. Supply the continuationToken in your next GET request as a URL parameter to retrieve the next set of data. If you don't provide the continuationToken, LiquidPlanner will return the first set of rows again.

Continuation Token Pagination Example

The example below demonstrates how to use a Continuation Token in two parts, Request 1 and Request 2.

Request 1 is a GET request that doesn't have a limit defined. In this instance the API applies 500 as the recordLimit since that is the maximum number of rows that can be requested at a time. The recordCount is also 500, indicating that we have retrieved the maximum number of records allowed. The continuationToken is supplied because there are more records to retrieve.

Request 1: /api/workspaces/<workspace id>/items/v1
"id": 50452 - This is the LiquidPlanner ID of the first item retrieved.
"continuationToken": 55254 - This is the LiquidPlanner ID of the last item retrieved. Use this token to fetch next set of records.

The continuationToken is supplied in GET Request 2 below. Anytime you make a request, data is returned in ascending order by LiquidPlanner ID. Therefore, the "id" of the first record returned will always be higher than the "id" that was used for the Continuation Token. In this example the they are continuous, but that may not always be the case. The presence of a continuationToken in this result lets us know there are more records to retrieve. Keep making requests until the the tokens stop.

Request 2: /api/workspaces/<workspace id>/items/v1?continuationToken=55254
"id": 55255 - This is the first record returned based on the Continuation Token.
"continuationToken": 176921 - This is the LiquidPlanner ID of the last item retrieved. Use this token to fetch the next set of records.