# Pagination

List endpoints return collection responses with pagination fields when the underlying resource supports paging.

Use pagination whenever you read data that can grow with customer communication volume: contacts, conversations, messages, teams, properties, journeys, or billing records. A small tenant may fit in one response today and need multiple pages later.

## List responses

Most paginated list endpoints accept a `pageToken` query parameter and return `nextPageToken` when another page is available. Endpoint pages document the exact response schema and array field name.

Build clients around the documented fields for that endpoint instead of assuming that every list uses the same record array name.

Typical fields include:

- an array of records,
- `nextPageToken` for the next page,
- optional count or metadata fields,
- filters that control which records are returned.

## Syncing data into your systems

When exporting Flownally data into a CRM, warehouse, or internal support tool, process one page at a time and persist progress after each successful page. That keeps a long-running sync from starting over if it is interrupted.

```ts
let pageToken: string | undefined;

do {
  const page = await listContacts({ pageToken, limit: 100 });
  await saveContacts(page.contacts);
  pageToken = page.nextPageToken;
} while (pageToken);
```

Use stable filters where available. Prefer updated-time filters for incremental syncs, and run full backfills only when you need to rebuild local state.

## Page size

Choose a page size that your job can process comfortably. Larger pages reduce request count, but they also increase memory usage and retry cost. Smaller pages are easier to resume and safer for customer-facing automation.

For background jobs, start with a moderate limit and measure:

- API latency,
- processing time per page,
- downstream write time,
- retry frequency.

Then tune the limit for your workload.