Skip to main content

Pagination - APIv2

Updated

How list endpoints page their results and how to iterate through every page.

List endpoints return results one page at a time. You control the page with query parameters and follow the nextPage link in the response until there are no more pages.

Source: https://propelus.com/developer/getting-started/pagination

Request parameters

Parameter Type Default Range Description
page integer 1 1 to 100 Which page to return.
perPage integer 10 1 to 100 Number of items per page. 
curl "https://api.demo.propelus.com/v2/professionals?page=1&perPage=25" \  
  -H "x-api-key: $PROPELUS_API_KEY" \  
  -H "x-client-id: $PROPELUS_CLIENT_ID"

Response envelope

Paginated responses wrap the items in a consistent envelope:

{  
  "count": 25,  
  "total": 213,  
  "professionals": [ /* ... items for this page ... */ ],  
  "nextPage": "/v2/professionals?page=2&perPage=25",  
  "prevPage": null
}
Field Description
count Number of items on the current page.
total Total number of items across all pages.
nextPage Relative path to the next page, or null on the last page.
prevPage Relative path to the previous page, or null on the first page.

The array field is named after the resource (professionals, credentials, webhooks).

Iterating through all pages

Follow nextPage until it is null. Because it's a ready-made relative path, you can append it directly to the base URL, rather than assembling query strings yourself.

async function 
  fetchAll(path: string) {  
  const base = "https://api.demo.propelus.com";  const headers = {    
    "x-api-key": process.env.PROPELUS_API_KEY!,    
    "x-client-id": process.env.PROPELUS_CLIENT_ID!,  
  };  
  
  const all = [];  
  let next: string | null = path; // e.g. "/v2/professionals?perPage=100"  
  
  while (next) {    
    const res = await fetch(base + next, { headers });    
    const body = await res.json();    
    all.push(...body.professionals);    
    next = body.nextPage; // null on the last page ends the loop  
  }  
  
  return all;
}

Request the largest perPage (up to 100) that your processing can handle to minimize round trips, and add a short backoff between pages if you're iterating large result sets. See Rate limits.

Which endpoints paginate

These list endpoints use page/perPage and the envelope described above:

Other list endpoints (for example GET /v2/professions) return their full result set in a single response and are not paginated.

Related articles