Record Limits & Pagination

When working with the TrackVia API, it's important to understand the limits on how many records can be returned in a single request. To work with large datasets, you'll need to use pagination. This guide explains the record limits and provides best practices for fetching data efficiently.

Record Limits

The TrackVia API imposes the following limits on record retrieval:

Default Limit: By default, API endpoints that return records (like GET /api/v1/views/{viewId}/records) will return a maximum of 1,000 records per request. If you don't specify a max parameter, you'll get up to 1,000 records.
Maximum Limit: The absolute maximum number of records you can request in a single API call is 100,000. You can set this with the max parameter. Attempting to request more than 100,000 records will result in an error.
Other Limits: Be aware that some specific operations have their own hardcoded limits. For example, batch updates using AppScripts are limited to 1,000 records.

Key takeaway: The API is designed to handle large amounts of data, but it encourages retrieving it in manageable chunks.

Best Practices for Large Datasets

Instead of fetching a massive number of records and then filtering them on your application's side, it's far more efficient to pre-filter the data within TrackVia.

Create specific views in TrackVia that contain only the data you need. By applying filters in the TrackVia user interface to create a targeted view, your API calls will be faster and use fewer resources, both for your system and for TrackVia.

How to Use Pagination

To retrieve more than the default 1,000 records, or to break up a large request into smaller chunks, you can use the start and max query parameters.

start: This parameter defines the starting point for the record set (the offset). It's 0-indexed, so start=0 begins with the first record.
max: This parameter specifies the maximum number of records to return in the request (the limit).

Pagination Example

Here’s how you would retrieve a large set of records in pages of 1,000:

Request 1: Get the first 1,000 records

GET /api/v1/views/{viewId}/records?start=0&max=1000

Request 2: Get the next 1,000 records

GET /api/v1/views/{viewId}/records?start=1000&max=1000

Request 3: Get the following 1,000 records

GET /api/v1/views/{viewId}/records?start=2000&max=1000

You would continue this pattern, incrementing the start parameter by the max value for each subsequent request, until you have retrieved all the records you need.

Node SDK Example

For more information about our official Node SDK, please see the SDK page. Here is an example in JavaScript showing how to fetch all records from a view by paginating through the results.

const trackviaApi = require('trackvia-api');
 
// Authenticate with the API first
// This is a simplified example. Store credentials securely.
trackviaApi.login('YOUR_USERNAME', 'YOUR_PASSWORD')
  .then(() => {
    fetchAllRecords(YOUR_VIEW_ID);
  })
  .catch(error => {
    console.error('Authentication failed:', error);
  });
 
 
async function fetchAllRecords(viewId) {
  let allRecords = [];
  let start = 0;
  const max = 1000;
  let hasMoreRecords = true;
 
  while (hasMoreRecords) {
    try {
      const paging = { start, max };
      const records = await trackviaApi.getView(viewId, paging);
 
      if (records && records.length > 0) {
        allRecords = allRecords.concat(records);
        start += max; // Increment start for the next page
      } else {
        hasMoreRecords = false; // No more records to fetch
      }
    } catch (error) {
      console.error(`Error fetching records for view ${viewId}:`, error);
      hasMoreRecords = false;
    }
  }
 
  console.log(`Total records fetched: ${allRecords.length}`);
  return allRecords;
}

This function continuously fetches records in chunks of 1,000 and adds them to an array until no more records are returned.

Limitations FAQ