Pagination

The SDK provides multiple ways to handle paginated results.

Basic Pagination

List methods return paginated responses by default:

const response = await client.risks.list();

console.log(response.data);       // Array of risks
console.log(response.meta);       // Pagination metadata
console.log(response.links);      // Navigation links

Response Structure

interface ListResponse<T> {
  data: T[];                    // Array of resources
  meta: {
    totalCount: number;         // Total number of items
    pageCount: number;          // Total number of pages
    currentPage: number;        // Current page number
    perPage: number;            // Items per page
    hasMore?: boolean;          // Whether more pages exist
    nextCursor?: string;        // Cursor for next page
  };
  links: {
    self: string;               // Current page URL
    first: string;              // First page URL
    last: string;               // Last page URL
    next?: string;              // Next page URL (if exists)
    prev?: string;              // Previous page URL (if exists)
  };
}

Page-Based Pagination

Navigate using page numbers:

// Get page 1 with 25 items per page
const page1 = await client.risks.list({
  page: { number: 1, size: 25 }
});

// Get page 2
const page2 = await client.risks.list({
  page: { number: 2, size: 25 }
});

Cursor-Based Pagination

Use cursors for consistent pagination:

let cursor: string | undefined;
let allRisks: Risk[] = [];

do {
  const response = await client.risks.list({ cursor, limit: 100 });
  allRisks.push(...response.data);
  cursor = response.meta.nextCursor;
} while (cursor);

console.log(`Fetched ${allRisks.length} risks`);

Auto-Pagination

The easiest way to iterate over all resources:

// Async iterator - automatically fetches all pages
for await (const risk of client.risks.listAll()) {
  console.log(risk.name);
}

With Options

// Apply filters while auto-paginating
for await (const risk of client.risks.listAll({
  filter: { severity: 'high' },
  sort: '-createdAt',
})) {
  console.log(`${risk.name} - ${risk.severity}`);
}

Collect All Items

// Collect all items into an array
const allRisks: Risk[] = [];
for await (const risk of client.risks.listAll()) {
  allRisks.push(risk);
}

// Or using Array.fromAsync (Node 22+)
const risks = await Array.fromAsync(client.risks.listAll());

Pagination Options

Option	Type	Description
page.number	number	Page number (1-indexed)
page.size	number	Items per page (default: 25, max: 100)
cursor	string	Cursor from previous response
limit	number	Number of items to fetch
sort	string	Sort field (prefix with - for descending)

Examples

Display All Risks

console.log('All Risks:');
console.log('-'.repeat(40));

for await (const risk of client.risks.listAll()) {
  console.log(`• ${risk.name}`);
  console.log(`  Severity: ${risk.severity}`);
  console.log(`  Status: ${risk.status}`);
  console.log();
}

Count Items

let count = 0;
for await (const _ of client.controls.listAll()) {
  count++;
}
console.log(`Total controls: ${count}`);

Early Exit

// Stop after finding a specific item
for await (const risk of client.risks.listAll()) {
  if (risk.severity === 'critical') {
    console.log('Found critical risk:', risk.name);
    break; // Stop fetching more pages
  }
}

Parallel Processing

// Process items in batches
const batchSize = 10;
let batch: Risk[] = [];

for await (const risk of client.risks.listAll()) {
  batch.push(risk);
  
  if (batch.length >= batchSize) {
    await Promise.all(batch.map(r => processRisk(r)));
    batch = [];
  }
}

// Process remaining items
if (batch.length > 0) {
  await Promise.all(batch.map(r => processRisk(r)));
}

Performance Tips

Limit Fields

Reduce response size by selecting only needed fields:

const response = await client.risks.list({
  fields: { risks: ['id', 'name', 'severity'] }
});

Reasonable Page Sizes

Balance between request count and response size:

// Too small - many requests
const slow = await client.risks.list({ page: { size: 5 } });

// Good balance
const optimal = await client.risks.list({ page: { size: 50 } });

// Maximum allowed
const max = await client.risks.list({ page: { size: 100 } });

Next Steps

• Filtering - Filter results
• API Reference - All available methods