Pagination

Basic Pagination Parameters

When making requests to paginated endpoints, you can include the following query parameters:

Example: Retrieving the First Page

To retrieve the first page of results, simply make a request without a cursor:

// Using the Telesoft SDK
const telesoft = new TelesoftAI({
  apiKey: 'YOUR_API_KEY',
  environment: 'production'
});

// Get the first page of patients
const patientsPage = await telesoft.patients.list({
  limit: 50,
  order: 'created_at:desc'
});

console.log(`Showing ${patientsPage.data.length} of ${patientsPage.pagination.total_count} patients`);
console.log(`Has more: ${patientsPage.pagination.has_more}`);
console.log(`Next cursor: ${patientsPage.pagination.next_cursor}`);

Example: Retrieving Subsequent Pages

To retrieve the next page of results, use the next_cursor from the previous response:

// Continue from the previous example
if (patientsPage.pagination.has_more) {
  // Get the next page using the next_cursor
  const nextPage = await telesoft.patients.list({
    limit: 50,
    cursor: patientsPage.pagination.next_cursor,
    direction: 'next' // This is the default, so it could be omitted
  });
  
  console.log(`Showing next ${nextPage.data.length} patients`);
  
  // To go back to the previous page
  const prevPage = await telesoft.patients.list({
    limit: 50,
    cursor: nextPage.pagination.prev_cursor,
    direction: 'prev'
  });
}

Example: Automatic Pagination

// Using async iteration to process all patients
async function processAllPatients() {
  let cursor = null;
  let hasMore = true;
  const limit = 100; // Max limit for efficiency
  const processedIds = new Set();
  
  while (hasMore) {
    const response = await telesoft.patients.list({
      limit,
      cursor,
      created_after: '2023-01-01T00:00:00Z' // Optional filtering
    });
    
    // Process each patient in this page
    for (const patient of response.data) {
      // Skip if we've already processed this patient (safety check)
      if (processedIds.has(patient.id)) continue;
      
      // Process the patient
      await processPatient(patient);
      
      // Mark as processed
      processedIds.add(patient.id);
    }
    
    // Update pagination state for next iteration
    hasMore = response.pagination.has_more;
    cursor = response.pagination.next_cursor;
    
    // Optional: Add delay between requests to avoid rate limiting
    if (hasMore) {
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  }
  
  console.log(`Processed ${processedIds.size} patients in total`);
}

// Function to process an individual patient
async function processPatient(patient) {
  console.log(`Processing patient: ${patient.id} - ${patient.name}`);
  // Your processing logic here
}

SDK Pagination Helpers

The Telesoft SDK provides helper methods to simplify pagination:

// Using the SDK's auto-pagination feature
const allPatients = await telesoft.patients.listAll({
  created_after: '2023-01-01T00:00:00Z',
  limit: 100,
  maxPages: 10 // Optional: limit the maximum number of pages
});

console.log(`Retrieved ${allPatients.length} patients in total`);

// Using the SDK's iterator for more controlled pagination
const patientIterator = telesoft.patients.listAutoPaginate({
  created_after: '2023-01-01T00:00:00Z',
  limit: 100
});

let count = 0;
for await (const page of patientIterator) {
  count += page.data.length;
  console.log(`Processed page with ${page.data.length} patients`);
  
  // You can break the loop at any point
  if (count >= 500) break;
}

Specifying Sort Order

You can specify the sort order using the order parameter:

// Sort by creation date in descending order (newest first)
const patients = await telesoft.patients.list({
  order: 'created_at:desc',
  limit: 50
});

// Sort by name in ascending order (A to Z)
const patientsAlphabetical = await telesoft.patients.list({
  order: 'name:asc',
  limit: 50
});

// Sort by multiple fields (primary: last_updated, secondary: name)
const patientsSorted = await telesoft.patients.list({
  order: ['last_updated:desc', 'name:asc'],
  limit: 50
});

Pagination with Sorting

// Example of consistent sorting across paginated requests
async function fetchAllPatientsWithDiabetes() {
  const sortOrder = 'last_visit:desc';
  let cursor = null;
  let hasMore = true;
  const results = [];
  
  while (hasMore) {
    const response = await telesoft.patients.list({
      filter: 'medical_history:contains:diabetes',
      order: sortOrder, // Use the same sort order for all requests
      cursor,
      limit: 100
    });
    
    results.push(...response.data);
    hasMore = response.pagination.has_more;
    cursor = response.pagination.next_cursor;
  }
  
  return results;
}

Optimizing Pagination Performance

• Use appropriate limits: Set the limit parameter based on your application's needs. Higher limits mean fewer API calls but larger response payloads.
• Implement lazy loading: For user interfaces, load additional pages only when needed rather than preloading all data.
• Cache results: Consider caching paginated results to reduce API calls, especially for data that doesn't change frequently.
• Use filtering: Apply appropriate filters to reduce the total dataset size before pagination.

Handling Edge Cases

• Empty result sets: When no items match your query, the response will contain an empty data array and pagination metadata with has_more: false and next_cursor: null.
• Data changes during pagination: If new items are added or existing items are modified while you're paginating, cursor-based pagination ensures you won't miss or duplicate items.
• Cursor expiration: Cursors typically remain valid for 24 hours. If you attempt to use an expired cursor, the API will return an error.

// Example of handling empty results and expired cursors
async function getPatientPage(cursor) {
  try {
    const response = await telesoft.patients.list({
      cursor,
      limit: 50
    });
    
    if (response.data.length === 0) {
      console.log('No matching patients found.');
    }
    
    return response;
  } catch (error) {
    if (error.code === 'invalid_cursor') {
      console.error('The pagination cursor has expired. Starting a new pagination session.');
      // Restart pagination without a cursor
      return telesoft.patients.list({ limit: 50 });
    }
    throw error;
  }
}

Filtering with Pagination

Combine pagination with filtering to process specific subsets of data:

// Get all patients created in a specific date range
const patientsInDateRange = await telesoft.patients.list({
  created_after: '2023-01-01T00:00:00Z',
  created_before: '2023-02-01T00:00:00Z',
  limit: 100
});

// Get all patients with a specific diagnosis
const patientsWithDiagnosis = await telesoft.patients.list({
  filter: 'diagnoses:contains:J45.9', // ICD-10 code for asthma
  limit: 100
});

// Combining multiple filters with pagination
const elderlyCovid = await telesoft.patients.list({
  filter: [
    'age:gte:65',
    'diagnoses:contains:U07.1' // ICD-10 code for COVID-19
  ],
  order: 'last_visit:desc',
  limit: 50
});

Pagination with Include Options

Many API endpoints support including related resources in the response. This feature works with pagination:

// Get patients with their latest diagnostic results
const patientsWithDiagnostics = await telesoft.patients.list({
  include: ['latest_diagnostic', 'primary_care_physician'],
  limit: 25
});

// The response will include the related resources
console.log(patientsWithDiagnostics.data[0].latest_diagnostic);
console.log(patientsWithDiagnostics.data[0].primary_care_physician);