> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Learn how to paginate through large result sets in the Connectivity API

# 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:

| Parameter | Type    | Description                                                 |
| --------- | ------- | ----------------------------------------------------------- |
| `limit`   | integer | Number of records to return (maximum: 50)                   |
| `offset`  | integer | Number of records to skip before starting to return results |

## Basic Pagination Example

Here's how to paginate through a list of contacts in HubSpot:

```bash theme={null}
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:

```json theme={null}
{
  "data": [
    // ... array of records
  ],
  "pagination": {
    "hasMore": true,
    "nextOffset": 50
  }
}
```

### Response Fields

| Field                   | Type    | Description                                  |
| ----------------------- | ------- | -------------------------------------------- |
| `data`                  | array   | The records returned for this page           |
| `pagination.hasMore`    | boolean | Whether more records are available           |
| `pagination.nextOffset` | integer | The offset value to use for the next request |

## Retrieving All Records

To retrieve all records, make successive requests until `hasMore` is `false`:

```javascript theme={null}
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:

```javascript theme={null}
// ✅ 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

* Learn about [Executing Actions](/connectivity-api/quick-start#step-4%3A-execute-an-action)
* Explore [Filtering and Search](/mcp/core-concepts/restrictions-guide#how-the-filtering-works)
* Review [Rate Limits](/embedded/platform/monitoring/rate-limits)

## Need Help?

* [API Reference](/reference/connectivity-api/connectivity-api)
* [Support](mailto:support@runalloy.com)