| name | notion-load-scale |
| description | Use when you must move high volumes through the Notion API without tripping
its 3 req/sec limit — bulk-creating pages, syncing 100K+ record databases, or
running background jobs. Covers parallel requests within 3 req/sec, worker
queues, database pagination at scale, incremental sync for large workspaces,
and memory management for bulk operations.
Trigger with phrases like "notion scale", "notion bulk operations",
"notion high volume", "notion worker queue", "notion incremental sync".
|
| allowed-tools | Read, Write, Bash(node:*), Bash(npx:*) |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
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 last_edited_time 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 ;
apiQueue = ({ : , : , : });
results = .(
dbIds.( apiQueue.(
notion..({ : id, : })
))
);
