Skip to main content

​
Pagination

The AutoPaginatable class provides automatic pagination for list resources, allowing you to fetch all results across multiple pages with built-in rate limiting.

​
Installation

import { AutoPaginatable } from '@workos-inc/node';

​
Class

​
AutoPaginatable

A generic class that wraps paginated list responses and provides automatic pagination. 
class AutoPaginatable<ResourceType, ParametersType>
Type Parameters
​
ResourceType
generic
required
The type of resource being paginated (e.g., User, Organization)
​
ParametersType
PaginationOptions
default:"PaginationOptions"
Optional extended pagination parameters
Constructor Parameters
​
list
List<ResourceType>
required
The initial list response containing data and metadata
​
apiCall
(params: PaginationOptions) => Promise<List<ResourceType>>
required
Function to fetch the next page of results
​
options
ParametersType
Pagination options for subsequent requests

​
Properties

​
data

Access the current page of data. Type: ResourceType[] 
const paginatedList = new AutoPaginatable(response, fetchUsers);
console.log(paginatedList.data); // Array of users from current page

​
listMetadata

Access pagination metadata for the current page. Type: { before?: string | null; after?: string | null } 
console.log(paginatedList.listMetadata);
// { before: null, after: "user_123" }

​
options

The pagination options used for API calls. Type: ParametersType

​
object

Always returns 'list' to identify the response type. Type: 'list'

​
Methods

​
autoPagination()

Automatically paginates over the list of results, returning the complete data set. Implements automatic rate limiting (4 requests per second) to respect API rate limits. Returns
​
results
ResourceType[]
Array of all resources across all pages
Behavior
  • If options.limit was passed to the initial request, returns only the first page (data)
  • Otherwise, fetches all pages and returns the complete dataset
  • Automatically adds 350ms delay between requests (4rps rate limit)
  • Uses after cursor for pagination
Example 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_test_key');

// Get first page
const response = await workos.userManagement.listUsers();

// Get all users across all pages
const allUsers = await response.autoPagination();

console.log(`Total users: ${allUsers.length}`);

​
Types

​
PaginationOptions

Options for controlling pagination behavior.
​
limit
number
Maximum number of results per page
​
before
string | null
Cursor for fetching the previous page
​
after
string | null
Cursor for fetching the next page
​
order
'asc' | 'desc'
Sort order for results

​
List

The list response structure. 
interface List<T>
​
object
'list'
required
Always ‘list’
​
data
T[]
required
Array of resources
​
listMetadata
object
required
Pagination metadata
​
before
string | null
Cursor for previous page
​
after
string | null
Cursor for next page

​
Usage Examples

​
Paginate with limit

const workos = new WorkOS('sk_test_key');

// Fetch only first 50 users
const response = await workos.userManagement.listUsers({ limit: 50 });
const users = await response.autoPagination();

console.log(users.length); // 50 (only first page)

​
Paginate all results

// Fetch all users across all pages
const response = await workos.userManagement.listUsers();
const allUsers = await response.autoPagination();

console.log(allUsers.length); // Total count across all pages

​
Manual pagination

let response = await workos.userManagement.listUsers({ limit: 100 });
const users = [...response.data];

while (response.listMetadata.after) {
  response = await workos.userManagement.listUsers({
    limit: 100,
    after: response.listMetadata.after
  });
  users.push(...response.data);
}

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

​
Process results in batches

const response = await workos.userManagement.listUsers();

// Process first page immediately
processBatch(response.data);

// Then fetch and process remaining pages
if (response.listMetadata.after) {
  const remaining = await response.autoPagination();
  processRemainingBatches(remaining);
}

​
Rate Limiting

The autoPagination() method automatically implements rate limiting:
  • Adds 350ms delay between requests
  • Achieves ~4 requests per second
  • Respects WorkOS list API rate limits
  • No manual throttling required
// This automatically rate limits to 4rps
const allUsers = await response.autoPagination();

Build docs developers (and LLMs) love

Get started for freeTalk to us