---
title: "Limits and rate limits"
description: "Pagination, date windows, text sizes, response budgets, and per-grant MCP rate limits."
canonical_url: https://cadence-me.com/developers/limits
last_updated: 2026-10-18
status: stable
source: src/data/developers.ts
---

# Limits and rate limits

## Contract limits

| Limit | Value |
|---|---|
| Default page size | 50 |
| Maximum page size | 100 |
| `list_occurrences` maximum date range (days, inclusive) | 92 |
| `get_adherence_summary` maximum date range (days, inclusive) | 366 |
| `get_timeline` maximum days | 14 |
| Needs decision lookback (days) | 90 |
| Needs decision items returned | 100 |
| Behavior ids per filter | 50 |
| Search query length (characters) | 200 |
| Search results | 20 |
| Behavior title length | 160 |
| Behavior description length | 1000 |
| Location text length | 500 |
| Schedules per Behavior | 6 |
| Time entries per schedule | 8 |
| Recurrence interval (input) | 999 |
| Default duration (minutes) | 1440 |
| Sub-behaviors per `create_behavior` call | 25 |
| Largest `sub_behavior_sort_order` | 9999 |
| Occurrences per `set_parent_occurrence_status` call | 50 |
| Occurrence note length | 2000 |
| Day note length | 2000 |
| `list_day_notes` maximum date range (days, inclusive) | 92 |
| Archive note length | 2000 |
| Cursor length | 512 |
| Revision length | 128 |
| Idempotency key minimum length | 8 |
| Idempotency key maximum length | 128 |
| External reference length | 200 |
| Idempotent replay window (seconds) | 86400 |
| Maximum result size (UTF-8 bytes) | 100000 |
| Reminder offsets (minutes) | 0, 15, 60, 1440, 4320 |

Existing longer notes can be read unchanged, subject to the result byte limit. The 2,000-character note cap applies to MCP writes. A response that exceeds 100,000 UTF-8 bytes fails; use a smaller page or date range. A single oversized record may still exceed the limit.

## Rate limits

Each grant allows 120 read calls and 30 write calls per minute in independent buckets. Scope checks happen before these counters. Honor Retry-After and retry_after_seconds instead of rapid polling.

OAuth protocol endpoints enforce 600 requests per minute globally and 60 per minute per source. Registration adds 10 per hour per source. Local and unrecognized proxy environments share one source bucket. Availability can therefore depend on other traffic.

## Transport limits

MCP request bodies allow 65,536 bytes and two seconds to read. Operation network requests share a 45-second abort deadline within the route's 60-second maximum. OAuth bodies allow 16 KiB and two seconds; OAuth database calls have an eight-second deadline.

Browser Origins are limited to the configured issuer, https://claude.ai and https://chatgpt.com. Development additionally permits HTTP localhost and 127.0.0.1 on ports 4321–4330. Server-to-server requests without Origin remain valid. Arbitrary third-party browser origins are not enabled; use a backend integration.

## Pagination and freshness

Follow next_cursor until null; keep filters unchanged across pages. Treat cursors as opaque and restart the query if a cursor is rejected. Timeline's Needs decision group has a bounded lookback and item cap; use list_occurrences for a wider history review. Freshness reports the server's data, not unsynchronized desktop changes.
