Skip to content

Pagination ​

All list endpoints support limit and offset query parameters for pagination.

Query Parameters ​

ParameterTypeDefaultRangeDescription
limitinteger101–100Maximum number of records to return
offsetinteger00+Number of records to skip

Response Format ​

Paginated responses include a data array with pagination metadata:

json
{
  "data": [
    { "id": "...", "name": "..." },
    { "id": "...", "name": "..." }
  ],
  "limit": 10,
  "offset": 0,
  "hasMore": true
}

Medical record endpoints also include a total field with the full count of matching records:

json
{
  "data": [ ... ],
  "limit": 10,
  "offset": 0,
  "total": 156,
  "hasMore": true
}

Response Fields ​

  • data — Array of resource objects
  • limit — The page size used for this request
  • offset — The number of records skipped
  • hasMore — true if more records exist beyond the current page
  • total — Total count of matching records (medical record endpoints only)

Usage Examples ​

Get First Page ​

http
GET /ext/latest/patients?limit=25&offset=0
Authorization: Bearer {token}

Response:

json
{
  "data": [
    { "patientId": "...", "firstName": "Jane", "lastName": "Doe" },
    { "patientId": "...", "firstName": "John", "lastName": "Smith" }
  ],
  "limit": 25,
  "offset": 0,
  "hasMore": true
}

Get Next Page ​

http
GET /ext/latest/patients?limit=25&offset=25
Authorization: Bearer {token}

Combine Pagination with Filters ​

Pagination parameters can be combined with query filters:

http
GET /ext/latest/patients?lastName=Smith&limit=5&offset=0
Authorization: Bearer {token}

Iteration Pattern ​

Use the hasMore flag to implement efficient pagination loops:

javascript
async function fetchAllPatients(token, limit = 25) {
  const patients = [];
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `/ext/latest/patients?limit=${limit}&offset=${offset}`,
      {
        headers: { Authorization: `Bearer ${token}` }
      }
    );

    const { data, hasMore: moreResults } = await response.json();
    patients.push(...data);
    hasMore = moreResults;
    offset += limit;
  }

  return patients;
}

Best Practices ​

  • Use appropriate limits — Smaller limits (10-25) reduce response size; larger limits (50-100) reduce API calls
  • Don't assume order — Results may not be in a guaranteed order unless documented per endpoint
  • Cache total counts — If you need a total count, make a separate query and cache the result
  • Handle large datasets — For very large datasets, consider batch exports or scheduled sync operations

Empty Results

If a page contains no results, the hasMore flag will be false. Ensure your loop terminates properly when data.length === 0.

Vivlio Health API Documentation