Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/apple-notes-rate-limits/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill apple-notes-rate-limits. Copyright stays with the author (MIT).

Apple Notes Rate Limits

Overview

Apple Notes has no formal API rate limits like cloud services do. However, there are practical throughput limits imposed by three systems: the Apple Events IPC bridge (osascript to Notes.app), the iCloud sync daemon (bird/cloudd) that must process each write, and the Notes.app SQLite database that handles concurrent access. Exceeding these practical limits causes timeouts (-1712), sync lag, or data loss when writes outpace iCloud's upload buffer. This guide documents safe operation rates and provides throttling patterns.

Prerequisites

• A tested Notes adapter that keeps note data out of command strings and logs.
• A bounded queue with an idempotency key or durable operation ledger for each write.
• An approved maintenance window and backup for bulk mutations; the rates below are conservative starting points, not a vendor guarantee.

Instructions

1. Begin below the listed rates and increase only after observing successful sync on every required device.
2. Serialize writes and deletes; do not retry a timed-out mutation until a durable idempotency check determines whether it succeeded.
3. Pause the queue and escalate if timeout, sync lag, or duplicate detection crosses the service threshold.
4. Do not terminate iCloud processes to recover throughput; preserve evidence and use normal OS recovery procedures.

Practical Rate Limits

Throttled Operation Queue

// src/rate-limit/throttle.ts
import { execSync } from "child_process";

interface ThrottleConfig {
  minDelayMs: number;
  maxRetries: number;
  backoffMultiplier: number;
}

const THROTTLE_CONFIGS: Record<string, ThrottleConfig> = {
  read:   { minDelayMs: 100,  maxRetries: 3, backoffMultiplier: 2 },
  write:  { minDelayMs: 1000, maxRetries: 5, backoffMultiplier: 2 },
  delete: { minDelayMs: 1000, maxRetries: 3, backoffMultiplier: 3 },
  search: { minDelayMs: 500,  maxRetries: 2, backoffMultiplier: 2 },
};

async function throttledExec<T>(
  operation: () => T,
  type: keyof typeof THROTTLE_CONFIGS = "write"
): Promise<T> {
  const config = THROTTLE_CONFIGS[type];
  let delay = config.minDelayMs;

  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      const result = operation();
      await new Promise(r => setTimeout(r, config.minDelayMs));
      return result;
    } catch (e: any) {
      if (attempt === config.maxRetries) throw e;
      console.warn(`Retry ${attempt + 1}/${config.maxRetries} after ${delay}ms: ${e.message}`);
      await new Promise(r => setTimeout(r, delay));
      delay *= config.backoffMultiplier;
    }
  }
  throw new Error("Unreachable");
}

Batch Operations with Rate Limiting

#!/bin/bash
# Batch create notes with throttling
INPUT_FILE="$1"  # JSON array of {title, body} objects
DELAY=1  # seconds between creates

jq -c '.[]' "$INPUT_FILE" | while IFS= read -r note; do
  title=$(echo "$note" | jq -r '.title')
  body=$(echo "$note" | jq -r '.body')
  osascript -l JavaScript -e "
    const Notes = Application('Notes');
    const n = Notes.Note({name: '$title', body: '$body'});
    Notes.defaultAccount.folders[0].notes.push(n);
    n.name();
  " && echo "Created: $title" || echo "FAILED: $title"
  sleep "$DELAY"
done

iCloud Sync Monitoring During Bulk Operations

# Monitor iCloud sync backlog during batch operations
watch -n 5 'echo "=== Sync Status ===";
  brctl status com.apple.Notes 2>/dev/null || echo "brctl unavailable";
  echo ""; echo "=== Note Count ===";
  osascript -l JavaScript -e "Application(\"Notes\").defaultAccount.notes.length" 2>/dev/null'

Error Handling

Output

The queue records operation type, opaque idempotency key, attempt count, latency, and outcome. It must not record note title, body, account identifiers, or raw Apple Event payloads. A bulk run ends with a reconciliation count and an explicit list of operations requiring review.

Examples

For a planned import, enqueue one create at a time with a unique source-record key, wait for the configured delay, and reconcile the resulting note count before advancing. If a create times out, query the durable ledger and the scoped target folder before deciding whether to retry; never blindly submit the same create again.

Resources

• Mac Automation Scripting Guide
• Apple Events Programming Guide
• iCloud Sync Architecture

Next Steps

For performance optimization beyond throttling, see apple-notes-performance-tuning. For monitoring sync health during operations, see apple-notes-observability.