Agent Skills: Notion Performance Tuning

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.

Step 2: Cache Responses with TTL-Based Invalidation

Use an LRU cache with per-operation TTLs (short for volatile data like search, longer for stable data like schemas) and invalidate entries on every write to keep reads consistent.

import { LRUCache } from 'lru-cache';
const cache = new LRUCache<string, any>({ max: 1000, ttl: 60_000, allowStale: false });
// Invalidate on write: for (const key of cache.keys())
//   if (key.startsWith(`db:${dbId}:`)) cache.delete(key);

See full implementation walkthrough for tiered TTL configuration, cursor-based cached pagination, write-through invalidation, and cache-stats monitoring.

Step 3: Parallel Requests with Rate-Limited Queue and Latency Monitoring

See parallel requests and latency monitoring for p-queue rate-limited parallelism, latency tracking with p50/p95 benchmarks, incremental sync, and memory-efficient streaming via async generators.

Output

• Reduced API call count through property selection, filtering, and batched block appends
• TTL-based caching with write-through invalidation for data consistency
• Parallel requests within Notion's 3 req/sec rate limit using p-queue
• Incremental sync fetching only changed pages since last sync timestamp
• Latency monitoring with p50/p95 tracking against target benchmarks
• Memory-efficient streaming for large datasets via async generators

Error Handling

| Issue | Cause | Solution | | ------- | ------- | ---------- | | Stale cache data | TTL too long for volatile data | Use shorter TTL (30s for search, 60s for queries) | | Rate limit despite queue | Other code paths making unqueued calls | Use a single shared p-queue instance across your app | | Memory pressure from cache | Too many entries or large payloads | Set max on LRU cache; use filter_properties to shrink payloads | | Pagination never ends | Circular cursor or API bug | Add max-iteration guard (if (requestCount > 50) break) | | Incremental sync misses | Clock skew between client and API | Subtract a 5-second buffer from lastSyncTime | | p50 latency above target | Cold cache or large responses | Pre-fetch critical pages; use filter_properties to reduce response size |

Examples

A complete NotionPerf class combining caching, rate limiting, and incremental sync, plus a before/after latency benchmark, lives in the examples reference. The essential surface:

const perf = new NotionPerf(process.env.NOTION_TOKEN!);
const results = await perf.query('db-id-here');  // cached + rate-limited
const updates = await perf.sync('db-id-here');   // fetches only changed pages

See the examples reference for the full class definition and the latency-comparison harness.

Resources

• Query a Database — filtering, sorting, pagination
• Append Block Children — batch up to 100 blocks
• Request Limits — 3 req/sec per integration
• Notion SDK (notion-sdk-js) — @notionhq/client source
• p-queue — promise-based rate-limited queue
• LRU Cache — TTL-based in-memory cache

Next Steps

After tuning request patterns, wire up event-driven invalidation instead of relying purely on TTL expiry: the notion-webhooks-events skill covers receiving Notion webhook events and invalidating exactly the cache keys that changed, which keeps caches fresh without shortening TTLs.