Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us