Some of Metriport’s endpoints are paginated - they return a limited amount of items each time they are requested. Each request being a single “page”.

In order to have access to all items, after we receive the items for the current page we can request the next page to the API.

Each response includes:

  • meta: the information about the response.
  • <items>: the list of items for the respective request, where items is named according to the respective type of data being requested - e.g., patients, documents.

And meta contains:

  • itemsOnPage: the amount of items on the current page.
  • itemsInTotal: (optional) the total amount of items in all pages - only available on the first page.
  • nextPage: (optional) the URL to return the next page; if not present, it means there’s not a next page
    • we’re on the last page.
  • prevPage: (optional) the URL to return the previous page; if not present, it means we’re on the first page.

​
Example

In the example below, we’re loading the first page (there’s no prevPage), with the default number of items per page. We can see the total amount of items included (113).

{
    "meta": {
        "nextPage": "https://api.metriport.com/medical/v1/patient?fromItem=01936b20-48f8-7d49-8bc6-50e0c4986011&count=50",
        "itemsOnPage": 50,
        "itemsInTotal": 113
    },
    ...
}

To get the next page, we can just call the URL on nextPage. When there’s no nextPage, it means we’re on the last one. As simple as that.

​
Pagination parameters

Metriport’s pagination is designed to simplify its usage, hiding away the complexity for most situations.

But, it can be customized using these parameters:

  • count: the number of items to be included in each page/response, optional. Defaults to 50 items per page. The maximum number of items per page is 500.
  • fromItem: the ID of the first item to be included in the current page, optional. If not provided, the first page will be returned.
  • toItem: the last item to be included in the current page, optional. If not provided, it will automatically be calculated based on firstItem and count.

Only two of the parameters above can be specified for each request.

​
Pagination in the SDK

The SDK includes support for the paginated endpoints in two ways:

  • a simpler “page” version of the function, in which we can just pass the respective page’s URL;
  • a more detailed version of the function, in which we can specify each pagination parameter individually.

Typically, one would use the simpler, dedicated “page” function after obtaining the first page:

const { meta, patients } = await metriportClient.listPatients({ facilityId });
// do something with the patients...
let nextPage = meta.nextPage;
while (nextPage) {
  const { meta, patients } = await metriportClient.listPatientsPage(nextPage);
  // do something with the patients...
  nextPage = meta.nextPage;
}

Alternatively, one can use the detailed version, providing each individual parameter separately when requesting each page:

await metriportClient.listPatients(facilityId, filters, {
  count: 10,
  fromItem: "019330c6-a57d-7211-93d4-5395705ff4eb",
});