Implementation:Openai Openai node Pagination

Knowledge Sources	Openai_Openai_node
Domains	SDK, Pagination
Last Updated	2026-02-15 12:00 GMT

Overview

The pagination module provides the abstract page infrastructure and concrete page classes (Page, CursorPage, ConversationCursorPage) that enable automatic and manual iteration over paginated API list responses.

Description

The module is built around AbstractPage<Item>, an abstract class implementing AsyncIterable<Item>. It provides the core pagination contract: subclasses must implement getPaginatedItems() to extract items from the response body, and nextPageRequestOptions() to produce request options for the next page (or null when exhausted). The abstract class provides hasNextPage(), getNextPage(), iterPages() for page-level async iteration, and the [Symbol.asyncIterator] for item-level auto-pagination.

Three concrete page classes are provided. Page<Item> represents a non-paginated list response with data and object fields; its nextPageRequestOptions() always returns null as it exists for forward compatibility. CursorPage<Item> implements cursor-based pagination using the last item's id as the after query parameter, guided by a has_more boolean flag. ConversationCursorPage<Item> is similar but uses a dedicated last_id field from the response body as the cursor rather than deriving it from item IDs.

The module also exports PagePromise, a specialized APIPromise subclass that resolves to a page instance and itself implements AsyncIterable<Item>. This enables the ergonomic pattern of iterating directly on an unawaited list call: for await (const item of client.resources.list()).

Usage

Pagination classes are used automatically by every .list() method in the SDK. Developers can iterate over items directly using for await on the list call, or manually control pagination by awaiting the PagePromise and calling hasNextPage() / getNextPage().

Code Reference

Source Location

• Repository: openai-node
• File: src/core/pagination.ts

Signature

export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
  abstract nextPageRequestOptions(): PageRequestOptions | null;
  abstract getPaginatedItems(): Item[];
  hasNextPage(): boolean;
  getNextPage(): Promise<this>;
  iterPages(): AsyncGenerator<this>;
  [Symbol.asyncIterator](): AsyncGenerator<Item>;
}

export class PagePromise<PageClass extends AbstractPage<Item>, Item>
  extends APIPromise<PageClass>
  implements AsyncIterable<Item> {
  [Symbol.asyncIterator](): AsyncGenerator<Item>;
}

export class Page<Item> extends AbstractPage<Item> {
  data: Array<Item>;
  object: string;
}

export class CursorPage<Item extends { id: string }> extends AbstractPage<Item> {
  data: Array<Item>;
  has_more: boolean;
}

export class ConversationCursorPage<Item> extends AbstractPage<Item> {
  data: Array<Item>;
  has_more: boolean;
  last_id: string;
}

Import

import { Page, CursorPage, ConversationCursorPage } from 'openai/core/pagination';

I/O Contract

Inputs

Name	Type	Required	Description
client	OpenAI	Yes	The OpenAI client instance, used internally to make subsequent page requests.
response	Response	Yes	The raw HTTP response from the list API call.
body	CursorPageResponse<Item> | ConversationCursorPageResponse<Item>	Yes	The parsed response body containing the data array and pagination metadata.
options	FinalRequestOptions	Yes	The original request options, used to build next-page requests.

Outputs

Name	Type	Description
data	Array<Item>	The array of items on the current page.
has_more	boolean	Whether additional pages exist (CursorPage and ConversationCursorPage only).
hasNextPage()	boolean	Returns true if there is a subsequent page to fetch.
getNextPage()	Promise<this>	Fetches and returns the next page.
iterPages()	AsyncGenerator<this>	Async generator yielding each page sequentially.
[Symbol.asyncIterator]	AsyncGenerator<Item>	Async iterator yielding each individual item across all pages.

Usage Examples

import OpenAI from 'openai';

const client = new OpenAI();

// Auto-paginating iteration (most common pattern)
for await (const file of client.files.list()) {
  console.log(file.id, file.filename);
}

// Manual page-level control
const page = await client.files.list();
console.log('First page items:', page.data.length);

while (page.hasNextPage()) {
  const nextPage = await page.getNextPage();
  console.log('Next page items:', nextPage.data.length);
}

// Iterating over pages explicitly
for await (const page of client.files.list().iterPages()) {
  console.log(`Page with ${page.data.length} items`);
}

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime