Paging and limiting an API request

Learn how to use the limit and page features on a LUSID API request

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 will not be allowed to pass the filter, effectiveAt, SortBy or asAt fields. That said, these fields can still be passed in the first request of the pagination request series. The subsequent requests - which use a pagination token - will still persist the parameters from the first request even if the fields are not explicitly passed.

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.