Notion Load & Scale

Overview

Patterns for high-volume Notion API usage within the 3 requests/second rate

limit. Covers parallel request orchestration with p-queue, worker queue

architecture for background processing, full database pagination at scale

(100K+ records), incremental sync using lasteditedtime filters to avoid

re-fetching unchanged data, and memory management for bulk operations via

streaming and chunked processing.

Full runnable TypeScript + Python implementations for all three steps live in

references/implementation.md; planning utilities

live in references/examples.md.

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• p-queue for rate-limited concurrency (npm install p-queue)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN set (each token gets its own 3 req/s limit)
• Test database in Notion (dedicated for load testing)

Authentication

All operations authenticate with a Notion internal integration token in the

NOTION_TOKEN environment variable; the SDKs send it as a Bearer token

automatically. Each token has an independent 3 req/s limit — the key lever

for horizontal scaling. Full auth notes, including raw curl headers, are in

references/implementation.md.

Instructions

The three patterns compose: rate-limited calls (Step 1) are the primitive the

worker queue (Step 2) and the streaming paginator (Step 3) both build on. Read

the lean summary here, then open

references/implementation.md for the complete

code.

Step 1: Parallel Requests Within Rate Limits

Notion enforces 3 requests/second per integration token. Drive every call

through a single p-queue tuned to interval: 340 / intervalCap: 1 (~3/s

with a safety margin) rather than relying on concurrency alone, and wrap each

call so a rate_limited (429) response honors retry-after and retries once.

import PQueue from 'p-queue';

const apiQueue = new PQueue({ concurrency: 1, interval: 340, intervalCap: 1 });

// Every Notion call goes through this queue; add 429 retry inside (see refs).
const results = await Promise.all(
  dbIds.map(id => apiQueue.add(() =>
    notion.databases.query({ database_id: id, page_size: 100 })
  ))
);

Full wrapper (metrics, retry-after handling, Python token-bucket variant) is

in Step 1 of references/implementation.md.

Step 2: Worker Queue Architecture for Background Processing

For sustained high-volume writes, decouple API calls from user requests with a

job queue. A NotionWorkerQueue wraps the same rate-limited p-queue, dispatches

by job type (create/update/query/append), retries rate_limited jobs with

exponential backoff, and routes jobs past maxRetries to a dead-letter list. See Step 2 of

references/implementation.md for the full class

plus a 500-page bulk-create example (~170s at 3/s).

Step 3: Pagination at Scale, Incremental Sync, Memory Management

For 100K+ record databases, stream pages through an async generator so results

are processed a batch at a time instead of loading everything into memory. Layer

incremental sync on top: filter by lasteditedtime onorafter your last

run and persist the server-returned timestamp between runs — cutting subsequent

API calls by 90%+.

async function* paginateDatabase(databaseId: string, filter?: any) {
  let cursor: string | undefined;
  do {
    const res = await notion.databases.query({
      database_id: databaseId, filter, page_size: 100, start_cursor: cursor,
    });
    yield res.results;                       // process a batch, then release it
    cursor = res.has_more ? res.next_cursor ?? undefined : undefined;
  } while (cursor);
}

Full streaming processor, incremental-sync driver with persisted state, and the

Python generator + multi-token scaling helper are in Step 3 of

references/implementation.md.

Output

• Rate-limited parallel requests maximizing 3 req/s throughput
• Worker queue with priority, retries, and dead letter handling
• Streaming pagination for 100K+ record databases
• Incremental sync reducing API calls by 90%+ on subsequent runs
• Memory-efficient processing via async generators

Error Handling

Examples

• Capacity Calculator — estimate whether a planned read/write mix fits your

token budget before a bulk run (accounts for cache hit rate + multi-token

scaling).

• Quick Throughput Benchmark — time 10 sequential calls to measure baseline

per-call latency without tripping the rate limit.

Both utilities, with full code, are in

references/examples.md.

Resources

• Notion Request Limits
• Notion Pagination
• p-queue - Promise Queue with Concurrency Control
• Notion Database Query Filter

Next Steps

For reliability patterns, see notion-reliability-patterns.

For architecture decisions at scale, see notion-architecture-variants.