Skip to main content

​
Pagination

Many list operations in the Connectivity API support pagination to handle large result sets efficiently. Pagination allows you to retrieve data in manageable chunks rather than loading all records at once.

​
How Pagination Works

The Connectivity API uses offset-based pagination. You control pagination using two parameters in your request:
ParameterTypeDescription
limitintegerNumber of records to return (maximum: 50)
offsetintegerNumber of records to skip before starting to return results

​
Basic Pagination Example

Here’s how to paginate through a list of contacts in HubSpot: 
curl -X POST https://production.runalloy.com/connectors/hubspot/actions/listContacts/execute \
  -H "Content-Type: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "x-alloy-userid: 68c3229752345278627ae373" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "credentialId": "68d9876543210fedcba98765",
    "actionId": "listContacts",
    "input": {
      "limit": 50,
      "offset": 0
    }
  }'

​
Pagination Response

The API response includes both the data and pagination metadata: 
{
  "data": [
    // ... array of records
  ],
  "pagination": {
    "hasMore": true,
    "nextOffset": 50
  }
}

​
Response Fields

FieldTypeDescription
dataarrayThe records returned for this page
pagination.hasMorebooleanWhether more records are available
pagination.nextOffsetintegerThe offset value to use for the next request

​
Retrieving All Records

To retrieve all records, make successive requests until hasMore is false: 
async function getAllContacts(credentialId, userId) {
  let allContacts = [];
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      'https://production.runalloy.com/connectors/hubspot/actions/listContacts/execute',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${YOUR_API_KEY}`,
          'x-api-version': '{API_VERSION}',
          'x-alloy-userid': userId,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          credentialId: credentialId,
          actionId: 'listContacts',
          input: {
            limit: 50,
            offset: offset
          }
        })
      }
    );

    const result = await response.json();
    allContacts = allContacts.concat(result.data);
    
    hasMore = result.pagination.hasMore;
    offset = result.pagination.nextOffset;
  }

  return allContacts;
}

​
Pagination Limits

  • Maximum limit: 50 records per request
  • Default limit: Varies by connector (check connector documentation)
  • Starting offset: Always start with offset: 0

​
Which Operations Support Pagination

Pagination is supported by most list operations across connectors, including:
  • Listing contacts
  • Listing companies
  • Listing deals
  • Listing tasks
  • Other list/search operations
Note: Pagination support may vary depending on the third-party platform’s API capabilities.

​
Best Practices

​
Choose Appropriate Page Sizes

Use smaller page sizes (10-50 records) for:
  • Real-time user interfaces
  • Operations with complex data transformations
  • Rate-limited connectors

​
Handle Pagination Metadata

Always check the hasMore field rather than assuming a fixed number of pages: 
// ✅ Good - relies on hasMore
while (result.pagination.hasMore) {
  // fetch next page
}

// ❌ Bad - assumes fixed number of records
for (let page = 0; page < 10; page++) {
  // fetch page
}

​
Next Steps

​
Need Help?

⌘I