Pagination

The SDK provides a paginate() helper function for automatically fetching all items from paginated list endpoints.

When to Use Pagination

Use pagination when fetching potentially large lists:

Listing all webhooks
Fetching audit history
Any endpoint that returns arrays with page and limit parameters

paginate() Helper

Import the pagination helper:

import { paginate } from '@vertaaux/sdk';

Signature

async function paginate<T>(options: {
  page?: number;           // Starting page (default: 1)
  limit?: number;          // Items per page (default: 50)
  fetchPage: (page: number, limit: number) => Promise<T[]>;
}): Promise<T[]>

Parameters

Parameter	Type	Required	Description
page	`number`	optional	Starting page number. Default: 1
limit	`number`	optional	Items per page. Default: 50
fetchPage	`(page, limit) => Promise<T[]>`	required	Async function that fetches a single page of results

How It Works

The paginate() function:

Calls fetchPage(page, limit) starting from the first page
Collects all returned items
If the page returns fewer items than limit, stops (end of data)
Otherwise, increments page and fetches the next batch
Returns all collected items as a single array

Basic Example

Fetch all webhooks across multiple pages:

import { VertaaUX, paginate } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

// Fetch all webhooks (handles pagination automatically)
const allWebhooks = await paginate({
  fetchPage: async (page, limit) => {
    const response = await client.webhooks.list({ page, limit });
    return response.webhooks ?? [];
  },
});

console.log(`Total webhooks: ${allWebhooks.length}`);
allWebhooks.forEach((wh) => {
  console.log(`- ${wh.id}: ${wh.url}`);
});

Custom Page Size

Control how many items are fetched per request:

const allWebhooks = await paginate({
  limit: 100, // Fetch 100 per page (fewer API calls)
  fetchPage: async (page, limit) => {
    const response = await client.webhooks.list({ page, limit });
    return response.webhooks ?? [];
  },
});

Starting from Specific Page

Resume pagination from a specific page:

// Skip first 2 pages, start from page 3
const webhooksFromPage3 = await paginate({
  page: 3,
  fetchPage: async (page, limit) => {
    const response = await client.webhooks.list({ page, limit });
    return response.webhooks ?? [];
  },
});

With Audit History

Fetch complete audit history:

import { VertaaUX, paginate } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

// Fetch all audits
const allAudits = await paginate({
  limit: 50,
  fetchPage: async (page, limit) => {
    // Assuming client.audits.list() exists
    const response = await fetch(
      `https://vertaaux.ai/api/v1/audits?page=${page}&limit=${limit}`,
      {
        headers: {
          'X-API-Key': process.env.VERTAA_API_KEY!,
        },
      }
    );
    const data = await response.json();
    return data.audits ?? [];
  },
});

console.log(`Total audits: ${allAudits.length}`);

// Analyze audit history
const completed = allAudits.filter((a) => a.status === 'completed');
const failed = allAudits.filter((a) => a.status === 'failed');

console.log(`Completed: ${completed.length}`);
console.log(`Failed: ${failed.length}`);

Manual Pagination

If you prefer manual control, handle pagination yourself:

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

async function* iterateWebhooks(pageSize = 20) {
  let page = 1;

  while (true) {
    const response = await client.webhooks.list({ page, limit: pageSize });
    const webhooks = response.webhooks ?? [];

    for (const webhook of webhooks) {
      yield webhook;
    }

    // Stop if we got fewer than requested (last page)
    if (webhooks.length < pageSize) {
      break;
    }

    page++;
  }
}

// Use the generator
for await (const webhook of iterateWebhooks()) {
  console.log(webhook.id, webhook.url);
}

Performance Considerations

Sequential vs Parallel

The paginate() helper fetches pages sequentially to avoid overwhelming the API. For faster fetching when you know the approximate count:

// Parallel fetch (faster but uses more API calls simultaneously)
async function fetchAllParallel(totalPages: number, pageSize: number) {
  const promises = Array.from({ length: totalPages }, (_, i) =>
    client.webhooks.list({ page: i + 1, limit: pageSize })
  );

  const responses = await Promise.all(promises);
  return responses.flatMap((r) => r.webhooks ?? []);
}

// Use when you know the total
const allWebhooks = await fetchAllParallel(5, 100); // 5 pages of 100

Parallel fetching counts against your rate limit. Use sequential pagination for production to avoid rate limiting.

Memory Usage

For very large datasets, process items in batches instead of loading all into memory:

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

// Process in batches without loading all into memory
async function processAllWebhooks(processor: (wh: Webhook) => Promise<void>) {
  let page = 1;
  const limit = 50;

  while (true) {
    const response = await client.webhooks.list({ page, limit });
    const webhooks = response.webhooks ?? [];

    // Process this batch
    for (const webhook of webhooks) {
      await processor(webhook);
    }

    if (webhooks.length < limit) break;
    page++;
  }
}

// Usage
await processAllWebhooks(async (webhook) => {
  console.log(`Processing: ${webhook.id}`);
  // Do something with each webhook
});

API Pagination Format

VertaaUX API endpoints use standard query parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number (1-indexed)
`limit`	number	20	Items per page (max: 100)

Response includes pagination metadata:

{
  "data": [...],
  "page": 1,
  "limit": 20,
  "total": 156
}

Webhook Methods - List webhooks with pagination
Audit Methods - Audit-related pagination
TypeScript Types - Response type definitions

Was this page helpful?

Pagination

On this page