notion-performance-tuning

name	notion-performance-tuning
description	Optimize Notion API performance with caching, batching, parallel requests, and incremental sync. Use when experiencing slow API responses, implementing caching strategies, reducing API call volume, or tuning request patterns for Notion integrations. Trigger with phrases like "notion performance", "optimize notion api", "notion latency", "notion caching", "notion slow", "notion batch requests", "notion incremental sync", "notion reduce api calls".
allowed-tools	Read, Write, Edit
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

Notion Performance Tuning

Overview

Optimize Notion API performance by minimizing API calls, caching responses with TTL-based invalidation, batching block appends, parallelizing requests within rate limits, selecting only needed properties, and implementing incremental sync patterns. Target latency benchmarks: Database Query p50=150ms, Page Create p50=200ms, Search p50=300ms.

Prerequisites

• @notionhq/client installed (npm install @notionhq/client)
• p-queue for rate-limited parallelism (npm install p-queue)
• lru-cache for TTL-based caching (npm install lru-cache)
• Authentication: a Notion integration token in NOTION_TOKEN (internal integration secret from https://www.notion.so/my-integrations), passed as new Client({ auth: process.env.NOTION_TOKEN })
• Understanding of your access patterns (read-heavy vs write-heavy)
• Optional: Redis or ioredis for distributed caching across instances

Instructions

Apply the three techniques in order — each builds on the previous one. The lean skeletons below are enough to follow the workflow; drill into the linked reference files for the complete, copy-paste-ready code.

Step 1: Minimize API Calls and Reduce Payload

Avoid N+1 patterns, page with page_size: 100 (the maximum), select only the properties you need with filter_properties, and batch block appends in chunks of 100.

// Batch block appends — up to 100 blocks per request (API maximum)
for (let i = 0; i < blocks.length; i += 100) {
  await notion.blocks.children.append({
    block_id: pageId,
    children: blocks.slice(i, i + 100),
  });
}

See full implementation walkthrough for the N+1-vs-batched query comparison, filter_properties usage, and selective block-tree expansion.