Notion API rate limits, the official numbers

The size caps that quietly break you first

The 3-per-second number gets all the attention. In practice, most of the production bugs I see on Notion integrations are not throttling. They are size errors that look like throttling because the call comes back with no useful body. Here are the per-request hard caps Notion publishes, in the same place as the rate limit.

The 1000-block and 500KB caps are what you hit when you write an importer or sync. They produce a clean validation error, not a 429, so you do not retry your way out. The fix is chunking on the way in, which a queue gets you for free but a naive loop does not.

The 15-minute window is the practical one to design against. If your sync runs 4 requests per second for 8 seconds then idles for two minutes, you are still under budget. If you run 3 per second flat for 16 minutes you will eventually 429 even though the instantaneous rate is on spec.

The workaround nobody writes about

The standard advice for hitting the limit is well known: queue, batch, exponential backoff, cache and diff. There is a fifth path that almost nobody writes up because it sounds wrong at first. You can simply not call the API. Drive the Notion macOS app through the accessibility tree the operating system already exposes, and your throughput is governed by UI latency and your own pacing, not by Notion's server-side rate limiter.

This is what Fazm uses for Notion specifically. The desktop app has a complete accessibility tree on macOS. An agent can walk it, identify the right database row, click into a page, type into a field, and confirm the write landed, all without authenticating against api.notion.com. Notion's own desktop client has no rate limit on what your hands can do, and accessibility-driven automation is, to the OS, just a faster pair of hands.

Why the OS path sidesteps the limit

Both paths end at the same Notion database. The difference is everything between you and that database. One traverses Notion's rate-limited public boundary. The other goes through your own logged-in session via the operating system.

The top route on the right is the one every guide tells you to optimize. The middle route is the one nobody covers, because most people writing about the Notion API are not also writing about macOS accessibility APIs. They are two different stacks. When you have an agent that already speaks both, the choice becomes a per-workflow decision instead of a religious one.

When the OS path is the right call

UI automation is not always the answer. It is the answer for a specific shape of work. Here is the honest version of when it pays off and when it does not.

The first four are the workflows where Fazm is the natural fit. The last three are the ones where you should stay on the public API and design around the 3-per-second budget, or move the data to a database that can keep up.

What about plan-based limits?

Notion's developer docs say, verbatim, that they plan to introduce distinct rate limits for workspaces in different pricing plans. That sentence has been on the page for a while now and the limits have not yet diverged in public docs. Today, the Free, Plus, Business, and Enterprise plans share the same 3-per-second average and the same per-request size caps. If higher limits ship on a paid plan in the future, Notion will update the same page where the 3-per-second number lives. The honest answer for now is that there is no paid escape hatch from the rate limit on api.notion.com.

That makes the per-workflow decision more interesting, not less. If the limit were just a free-tier nudge, the right answer would be a sales call. Since it applies to every plan, the right answer depends on the shape of the work.