Introduction
Some of LUSID's endpoint have the potential to return a very large number of results. For example, the list instruments or list quotes end-points could return thousands (or even millions) of results from one request. To help manage these requests, you can set limits on your requests to return X number of results and then use a pagination token to collect the next "page" of results from the same query.
The page and list parameters
The relevant LUSID APIs have two parameters to control pagination:
- Limit - you can specify how many results you want returned with the limit parameter. For example, calling list quotes has the potential to return thousands of results. You can set limit=100 to return the first 100 results only.
- Page - you can pass a pagination token to a request via the page parameter to continue listing results from a previous call which was limited. Continuing the list quotes example above, you could take the pagination token from your first response and pass this to your second request using the page parameter to list the next 100 results.
Paging with API parameters
If a pagination token is provided in a request, you are not allowed to change the api parameters passed from the initial request in the pagination series.
.Automatic limiting
To optimise system performance, many of LUSID's APIs will automatically implement a limit even if you do not specify one. For example, the list instruments API has an automatic limit of 2,000 instrument items in its response. As above, you can use the pagination token to collect more results if your request is limited.
Example
You can see an example below of a list instruments response which has a next_page and a previous_page token. The next_page will be blank if this is the last page.
Response 1: List instruments response with next_page and previous_page
<snip>
"next_page": "ABC123==",
"previous_page": "DEF123==",
"values": [
{
"href": "https://testdomain.lusid.com/api/api/instruments/LusidInstrumentId/CCY_AED",
"identifiers": {
"Currency": "AED",
"LusidInstrumentId": "CCY_AED"
},
"instrument_definition": null,
"links": null,
"lookthrough_portfolio": null,
"lusid_instrument_id": "CCY_AED"
}
]
<snip>
For a fully worked example, please see the paging and limiting LUSID's API calls notebook on the FINBOURNE GitHub page.