skills.rest
Duckshot-Productions
Duckshot-ProductionsOFFICIAL
Explore all skills by this author →
GitHub

sync-guide

Guides building Notion Workers syncs with pagination, cursors, and deletion strategies.

Updated Jul 31, 2026
Search Tags:#typescript#etl#data sync#pagination#incremental sync#cursor#notion workers
One-click install
npx skills add https://github.com/Duckshot-Productions/ntn-worker --skill sync-guide-duckshot-productions
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sync-guide
Source: https://github.com/Duckshot-Productions/ntn-worker/tree/main/.agents/skills/sync-guide
Command: npx skills add https://github.com/Duckshot-Productions/ntn-worker --skill sync-guide-duckshot-productions

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @notionhq/workers, and includes references (resource) components.

What problem does it solve? Building a reliable data sync into Notion requires choosing the right architecture, pagination strategy, and deletion handling for each external API, and mistakes like missing consistency buffers or non-advancing cursors cause permanent data loss or infinite loops. ## Core Features & Use Cases - Architecture Decision Framework: Choose between a simple replace-mode sync and a backfill+delta pair based on API change-tracking capability and dataset size. - Pagination & Cursor Patterns: Covers opaque cursors, page numbers, keyset (timestamp + id) pagination, event feeds, and consistency buffers drawn from Salesforce, Stripe, HubSpot, GitHub, and ServiceNow. - Deletion Strategies: Explains replace-mode mark-and-sweep, delete markers, and the flip-flop pattern for audit-log-based deletion detection. - Use Case: Sync HubSpot contacts into a Notion database by pairing a manual replace-mode backfill sync with a 5-minute incremental delta sync that handles search-API deadlocks. ## Quick Start Ask the agent to scaffold a Notion Workers sync for your external API, specifying the data source, whether it supports change tracking, and the desired schedule.

Frequently Asked Questions about sync-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I build a Notion Workers sync for an external API?▼

Define a managed database with worker.database, then register a sync with worker.sync whose execute function returns changes, hasMore, and nextState. Choose replace mode for small datasets or pair a manual backfill with a scheduled incremental delta sync for APIs with change tracking.

When should I use replace mode vs incremental mode in a sync?▼

Use replace mode when the API lacks change tracking or the dataset is small enough to re-fetch fully each cycle. Use incremental mode paired with a replace-mode backfill when the API supports updated_at filters, change feeds, or events.

Why does my incremental sync permanently miss records?▼

The cursor never resets in incremental mode, so advancing it past records not yet indexed by an eventually consistent API skips them forever. Add a consistency buffer of 10-60 seconds so the cursor stays behind the API's consistency frontier.

How do I handle deletions when the API has no delete signal?▼

Rely on a replace-mode backfill sync, which automatically deletes records not returned during a cycle. Trigger it manually or on a slow schedule to clean up stale records in the shared database.

How do I avoid rate limits in a Notion Workers sync?▼

Create a pacer with worker.pacer specifying allowedRequests and intervalMs, then call await pacer.wait() before every API request inside execute. The pacer budget is shared evenly across syncs hitting the same API.

What causes a sync to loop forever without finishing?▼

An infinite loop occurs when nextState does not change between iterations, so the cursor never advances. Ensure each execute call updates the cursor, page number, or token, and return hasMore: false when the final page is reached.

Related Skills

Explore More Software Engineering Skills→
memoirlabsmemoirlabs
6

notion-cli

Operates and manages Notion Serverless Functions and their triggers and schedules.

Official
Intermediate
john-data-chenjohn-data-chen
2

webhook-subscriptions

Create webhook subscriptions that trigger Hermes agent runs via POSTed events.

Community
Intermediate
photon-hqphoton-hq
14

imessage

Send and receive iMessages programmatically via WebSockets and AppleScript.

Official
Advanced
ax-llmax-llm
2.9k

ax-rust-ai

Generate Rust AxAI provider client code for axllm workflows.

Official
Intermediate