Pagination Helpers

Utilities for handling paginated API responses

The Notion SDK provides helper functions to simplify working with paginated API endpoints.

iteratePaginatedAPI

Returns an async iterator over the results of any paginated Notion API. This is memory-efficient for large datasets as it fetches pages on demand.

Signature

async function* iteratePaginatedAPI<Args extends PaginatedArgs, Item>(
  listFn: (args: Args) => Promise<PaginatedList<Item>>,
  firstPageArgs: Args
): AsyncIterableIterator<Item>

Parameters

• listFn - A bound function on the Notion client that represents a conforming paginated API (e.g., notion.blocks.children.list)
• firstPageArgs - Arguments that should be passed to the API on the first and subsequent calls. Any necessary next_cursor will be automatically populated by this function

Example

import { iteratePaginatedAPI } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_TOKEN })

for await (const block of iteratePaginatedAPI(notion.blocks.children.list, {
  block_id: parentBlockId,
})) {
  console.log(block.id, block.type)
}

collectPaginatedAPI

Collects all results of paginating an API into an in-memory array. Use this for smaller datasets when you need all results at once.

Signature

async function collectPaginatedAPI<Args extends PaginatedArgs, Item>(
  listFn: (args: Args) => Promise<PaginatedList<Item>>,
  firstPageArgs: Args
): Promise<Item[]>

Parameters

• listFn - A bound function on the Notion client that represents a conforming paginated API (e.g., notion.blocks.children.list)
• firstPageArgs - Arguments that should be passed to the API on the first and subsequent calls. Any necessary next_cursor will be automatically populated by this function

Example

import { collectPaginatedAPI } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_TOKEN })

const blocks = await collectPaginatedAPI(notion.blocks.children.list, {
  block_id: parentBlockId,
})

console.log(`Found ${blocks.length} blocks`)
blocks.forEach(block => {
  console.log(block.id, block.type)
})

When to Use Each Helper

Use iteratePaginatedAPI when:

• Working with large datasets that might not fit in memory
• You want to process items as they arrive
• You may not need all results (e.g., searching for a specific item)

Use collectPaginatedAPI when:

• The dataset is small enough to fit in memory
• You need all results before processing
• You need to perform operations that require the full dataset (sorting, filtering, etc.)

iterateDataSourceTemplates

A specialized iterator for data source templates. This helper simplifies iterating through all page templates available for a data source.

Signature

async function* iterateDataSourceTemplates(
  client: Client,
  args: ListDataSourceTemplatesArgs
): AsyncIterableIterator<DataSourceTemplate>

Parameters

• client - An instance of the Notion client
• args - Arguments for the dataSources.listTemplates API call, including data_source_id

Example

import { iterateDataSourceTemplates } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_TOKEN })

for await (const template of iterateDataSourceTemplates(notion, {
  data_source_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af"
})) {
  console.log(`Template: ${template.name} - ${template.description}`)
}

collectDataSourceTemplates

Collects all data source templates into an array. Use this when you need to work with the full list of templates at once.

Signature

async function collectDataSourceTemplates(
  client: Client,
  args: ListDataSourceTemplatesArgs
): Promise<DataSourceTemplate[]>

Parameters

• client - An instance of the Notion client
• args - Arguments for the dataSources.listTemplates API call, including data_source_id

Example

import { collectDataSourceTemplates } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_TOKEN })

const templates = await collectDataSourceTemplates(notion, {
  data_source_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af"
})

console.log(`Found ${templates.length} templates`)

// Find a specific template
const meetingTemplate = templates.find(t => t.name.includes("Meeting"))
if (meetingTemplate) {
  console.log(`Meeting template ID: ${meetingTemplate.id}`)
}

Supported Endpoints

These helpers work with any paginated Notion API endpoint, including:

• notion.blocks.children.list
• notion.dataSources.query
• notion.dataSources.listTemplates (use specialized helpers above)
• notion.users.list
• notion.comments.list
• notion.fileUploads.list
• notion.search