Handling paginated responses

Overview

Many Roblox APIs return paginated results with a cursor for fetching additional pages. RoZod provides helper functions to make pagination simple.

Fetching all pages at once

The fetchApiPages function automatically fetches all pages and returns an array of results:

import { fetchApiPages } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

// Automatically fetches all pages
const allPosts = await fetchApiPages(
  getGroupsGroupidWallPosts, 
  { groupId: 11479637 }
);

console.log(`Found ${allPosts.length} wall posts`);

fetchApiPages continues fetching until there are no more pages or the limit is reached.

Limiting pages

You can limit the maximum number of pages to fetch:

import { fetchApiPages } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

// Fetch at most 5 pages
const posts = await fetchApiPages(
  getGroupsGroupidWallPosts,
  { groupId: 11479637 },
  undefined, // requestOptions
  5          // limit
);

Processing pages incrementally

For large datasets, use fetchApiPagesGenerator to process pages one at a time:

import { fetchApiPagesGenerator } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

// Process pages as they arrive
const pages = fetchApiPagesGenerator(
  getGroupsGroupidWallPosts, 
  { groupId: 11479637 }
);

for await (const page of pages) {
  console.log(`Processing page with ${page.data.length} posts`);
  
  // Process this page's data
  page.data.forEach(post => {
    console.log(`Post by ${post.poster.username}: ${post.body}`);
  });
}

The generator approach is memory-efficient for large datasets since it only keeps one page in memory at a time.

Complete examples

Fetch all pages
Process incrementally
With error handling

import { fetchApiPages, isAnyErrorResponse } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

async function getAllGroupPosts(groupId: number) {
  const posts = await fetchApiPages(
    getGroupsGroupidWallPosts,
    { groupId }
  );

  if (isAnyErrorResponse(posts)) {
    console.error('Failed to fetch posts:', posts.message);
    return [];
  }

  // Flatten all pages into a single array
  return posts.flatMap(page => page.data);
}

const allPosts = await getAllGroupPosts(11479637);
console.log(`Total posts: ${allPosts.length}`);

import { fetchApiPagesGenerator } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

async function processGroupPosts(groupId: number) {
  const pages = fetchApiPagesGenerator(
    getGroupsGroupidWallPosts,
    { groupId }
  );

  let totalProcessed = 0;

  for await (const page of pages) {
    // Process each post in this page
    for (const post of page.data) {
      await processPost(post);
      totalProcessed++;
    }

    console.log(`Processed ${totalProcessed} posts so far...`);
  }

  return totalProcessed;
}

async function processPost(post: any) {
  // Your processing logic here
  console.log(`Processing post by ${post.poster.username}`);
}

await processGroupPosts(11479637);

import { 
  fetchApiPagesGenerator, 
  isAnyErrorResponse 
} from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

async function safelyFetchAllPosts(groupId: number) {
  const pages = fetchApiPagesGenerator(
    getGroupsGroupidWallPosts,
    { groupId }
  );

  const allPosts = [];

  for await (const page of pages) {
    // Check for errors on each page
    if (isAnyErrorResponse(page)) {
      console.error('Error fetching page:', page.message);
      break; // Stop on error
    }

    allPosts.push(...page.data);
  }

  return allPosts;
}

const posts = await safelyFetchAllPosts(11479637);

Advanced pagination

Custom request options

You can pass request options to pagination functions:

import { fetchApiPages } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

const posts = await fetchApiPages(
  getGroupsGroupidWallPosts,
  { groupId: 11479637 },
  {
    retries: 3,
    retryDelay: 1000,
    headers: {
      'Cookie': '.ROBLOSECURITY=your_cookie'
    }
  }
);

Early termination

With the generator, you can stop fetching at any time:

import { fetchApiPagesGenerator } from 'rozod';
import { getGroupsGroupidWallPosts } from 'rozod/lib/endpoints/groupsv2';

const pages = fetchApiPagesGenerator(
  getGroupsGroupidWallPosts,
  { groupId: 11479637 }
);

let foundTarget = false;

for await (const page of pages) {
  for (const post of page.data) {
    if (post.body.includes('important keyword')) {
      console.log('Found the post we were looking for!');
      foundTarget = true;
      break;
    }
  }
  
  if (foundTarget) break; // Stop fetching more pages
}

Always handle potential errors when using pagination. Network issues or API changes can cause failures mid-pagination.

Pagination vs batch processing

Use pagination when

The API returns results with nextPageCursor
You need all results from a multi-page response
You want to process results as they arrive

Use batch processing when

You have a large array of inputs
The API has limits on input array size
You need to split requests to avoid rate limits

Learn about batch processing →

Understanding cursors

Roblox APIs use cursor-based pagination:

The initial request returns the first page and a nextPageCursor
Pass the cursor in subsequent requests to get the next page
When nextPageCursor is null, there are no more pages

RoZod handles this automatically in fetchApiPages and fetchApiPagesGenerator.

// Manual cursor handling (not recommended)
let cursor = '';

while (true) {
  const page = await fetchApi(
    getGroupsGroupidWallPosts,
    { groupId: 11479637, cursor }
  );
  
  if (isAnyErrorResponse(page)) break;
  
  console.log(page.data);
  
  if (!page.nextPageCursor) break;
  cursor = page.nextPageCursor;
}

We recommend using fetchApiPages or fetchApiPagesGenerator instead of manual cursor handling.

Get Started

Core Concepts

Guides

Authentication

Handling paginated responses

Overview

Fetching all pages at once

Limiting pages

Processing pages incrementally

Complete examples

Custom request options

Early termination

Use pagination when

Use batch processing when

Understanding cursors

Next steps

Batch processing

Basic requests

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Authentication

​Overview

​Fetching all pages at once

​Limiting pages

​Processing pages incrementally

​Complete examples

​Advanced pagination

​Custom request options

​Early termination

​Pagination vs batch processing

Use pagination when

Use batch processing when

​Understanding cursors

​Next steps

Batch processing

Basic requests

Build docs developers (and LLMs) love

Overview

Fetching all pages at once

Limiting pages

Processing pages incrementally

Complete examples

Advanced pagination

Custom request options

Early termination

Pagination vs batch processing

Understanding cursors

Next steps