Pushing Notion to the Limits

Ben Borowski
January 18, 2023
Debugging, Notion, Tips

Introduction

While you can perform many of the same functions in *Notion as you can in traditional spreadsheet tools such as Google Sheets or Microsoft Excel, you may find that you reach the limits of what Notion can do as you begin doing more advanced data-heavy calculations and Formulas.

As a developer, *Notion Pro, Certified Consultant, and long-time user of Notion, I regularly run into the limits of what Notion can do, be they limits of the application itself or API limits. These limits can often block your progress, but sometimes it’s unclear as to why.

In this article, I’m curating a list of my understanding of Notion’s limitations: both documented and undocumented. If you’ve discovered a new limit or find any of these to be out-of-date, please let me know and I’ll update this guide.

Last update: Mar 5, 2024

Plan Limitations
In-App Limitations
API Limitations

Plan Limitations

What are the Block limits on the Plus plan trial?

👉 TL;DR: it’s 1,500 Blocks

The Free plan indicates that “Teams…can use the Free Plan with up to a certain number of blocks before upgrading.” Nice, but what is that “certain number”?

This is likely an encouragement to prompt you to upgrade, but the limit is 1,500 blocks. If you’ve ever used a template before, you’ll know that essentially you’ll hit this limit as soon as you add a template or two.

Keep in mind that this limit is ONLY on the Plus plan trial, so if you are on the Free plan or are paying for Notion, good news: no block limit!

What are the file upload size limits?

👉 TL;DR: 5MB on Free, 2GB on any paid plan

If you have a Free plan subscription, you can only upload files up to 5MB in size. On any paid plan, the file upload size is listed as “Unlimited”, but there is a soft limit according to Notion staff:

There’s a soft limit of 2GB per file – any larger and the upload may fail.

They also noted this in terms of having a Page with lots of large video files on it:

If you place many large video files within one page (or in one database), it will take longer for that specific page to load. However, general workspace performance across pages should not experience noticeable degradation.

Note here: in my experimentation with a page that hosts a large video, only small amounts of data are loaded from the video to present what is probably a “cover image”. It’s possible that lots (relative) of video files could indeed slow down page load.

Initial requests from a 785 MB video upload (only ~5 MB of that actually loaded).

How many Guests can I have?

The Guest limits by plan are currently:

Free: 10
Plus: 100
Business: 250
Enterprise: Custom*

*When the newer plans shipped recently, the Enterprise plan had a 500 Guest limit. I am not currently aware of what “Custom” means, but I can speculate that this means the soft-limit is 500 or Notion may be re-evaluating this limit. Waiting to hear back from the Notion team on this one!

What are the Synced Databases limits?

Synced Databases allow you to keep a Notion Database in sync with a third-party application. Currently supported services are Github and Jira. Synced Database support for Google Calendar was announced about a year ago but has not yet shipped (I think most users are most excited about that one!).

The Free plan gives you the ability to add 1 Synced Database with up to 100 rows. The 100 row limit on the Free plan will allow you to evaluate if you want to pay for Synced Databases.
All paid plans share the limit of 100 synced databases at 20,000 rows. 20,000 seems more than adequate for Github and Jira, but will that be sufficient for Google Calendar? 👀

What are the Page History limits?

Another well-documented limitation of the plans is how long the history of your Page updates is saved.

The Page History limits are currently:

Free: 7 days
Plus: 30 days
Business: 90 days
Enterprise: Unlimited

In-App Limitations

Getting a “Rate limit has been reached” message?

👉 TL;DR: There is a 50K Block duplication limit per hour

You may have seen this error if you have been duplicating a bunch of large templates or attempting to “move” large pages to another workspace. This is because there is an undocumented 50,000 block duplication limit per hour.

“Move” is in quotes here, because moving to another workspace is actually a duplication operation. Notion recently added this note about the limits to moving pages:

This is something you probably want to consider as you build large templates and systems. You may have to move them in pieces and then “fix” up relations in the other workspace.

Note: you may also see this message’s cousin “Unsaved transactions. Timed out.” This may also be an indication that you are currently rate-limited.

From Notion:

Once your account is rate limited you may experience…unsaved transactions. Again, the only way is to wait for the limit to reset at the next hour.

What is the Property reference limit?

👉 TL;DR: you can reference a formula property up to 7 times in a chain

Notion has a hard-coded limitation on formula property references in Formulas. This is to prevent both exponential calculations and to prevent circular logic.

The best way to understand this is to see a demo.

Referencing **Number** through Formulas eight times.

Each successive formula adds 1 to the previous formula.

Note here that Reference Number does not count as a formula reference since it is referencing a property and not a formula.

Some examples:

Formula Ref 1 → prop("Reference Number") + 1
Formula Ref 2 → prop("Formula Ref 1") + 1
Formula Ref 5 → prop("Formula Ref 4") + 1

You’ll note that on Formula Ref 8 the value is Empty. If we take a look at the formula here, we see a Maximum recusion depth exceeded error.

Maximum recursion depth exceeded — Uh oh

Note that there’s no known limit to referencing multiple properties in a single formula, but when your formula depends on another formula, that limit is 7.

This limit will also impact any “Calculations” you’ve applied at the bottom of Table Views. Confusingly even though the numbers work in the column up to 7 references, the calculations actually fail after the 6th reference. Below you can see how SUMing the Formula Ref 7 column is actually 0 and Formula Ref 8, being completely empty, is showing nothing for the sum. You can Formula Ref 7 to display accurately after refreshing the page (this seems like a bug), but the 8th will always be empty.

Long-winded editor’s note: if you are working with complex data-sets that rely on calculating lots of references, you may be better served by spreadsheet-specific software like Excel or Sheets.

For example, let’s check out this ultra-contrived demo in Google Sheets:

👉 Row Calculation Limits in Google Sheets

In this example, I have the number 1 in the A1 cell and then I wrote =$A1+1 in the A2 cell to add 1 to the previous row. Then I dragged the cell handle down 1000 rows and each successive row is calculated accurately based on the last, automatically updating the reference in each cell to refer to the previous cell.

This might be `prop("A1") + 1` as a Notion Formula

Further, let’s say I was interested in seeing how much a number of shares of $TLSA might be worth any time I open this sheet:

After adding `=GOOGLEFINANCE("NASDAQ:TSLA") * $A1` to cell B1

1,000 references with a call to the `GOOGLEFINANCE` API; no sweat

Combined with scripting and access to financial APIs, we can see that Notion might not be the best solution when it comes to more complex data modelling with financial data, especially when we need to calculate data based on loads of references.

A good reminder to select the right tool for the job (or data)!

Note: this reference limit also applies to Rollup references to other databases. So if you pull data from a Rollup and then reference that Rollup, you’ll start running into missing data after 7-references as well. More on this in Thomas Frank’s excellent Property Reference Limits documentation.

👉 TL;DR: no, but there are performance implications

This question gets asked a lot in Notion Mastery and throughout the web. According to Notion’s engineering team, there are no limits to the number of Pages that can be Related to another Page in a Database:

[There’s] no hardcoded limit to the number of relations that can be attached to a single page in a database. Just like with database rows/pages/entries, once you approach a couple thousand you’ll likely see performance degradation—but that would not compromise the accuracy of rollups.

As you can see here, there is no limit, however, if you are attaching 1,000s of related pages and utilizing Formulas, Rollups, or Calculate (in Table Views), it’s clear there will be performance implications. Said a different way: expect a slower experience as you add more related content.

Another note from a Notion engineer to reiterate:

The biggest thing that can make a database break is that we store relations as lists of page IDs, on the relation property itself, so if you have a single record that’s related to 10,000 other records, that can have adverse effects.

With regards to the statement “that would not compromise the accuracy of rollups”; this seems true for the application itself, but if you need to calculate Rollups based on a ton of Relations via the API, there are some major implications you’ll discover later in this document.

How long can I access uploaded files and media via link?

👉 TL;DR: In-app: 24 hours. Via API: 1 hour.

When you upload a file to Notion in a Page as a Block or in a Files & media Property, you can right click that file and select “View original”.

This will open a path to a file hosted on Amazon Web Services (AWS) S3.

When images are loaded in the Notion UI, a new public URL will be generated. These public URLs are only valid for 24 hours.

On the other hand, the API docs state that:

Each time a database or page is queried, a new public URL is generated for all files hosted by Notion. The public URLs are updated hourly and the previous public URLs are only valid for one hour.

So the API seems to shorten the validity to a single hour.

Will large select properties impact performance?

👉 TL;DR: possibly

A Notion engineer noted that a “select or multi-select property with thousands of choices can also slow things down a lot”, so it might be pertinent to curate and minimize the number of categories you add to your selects and multi-selects.

**Will having many Members impact performance?**

👉 TL;DR: yep

Because of how Notion loads workspace data and member listing, there may also be some performance implication in having a workspace with 1,000s of members, though likely it’d have to be in the 10s of 1,000s.

Most workspaces and/or businesses won’t run into this issue, but it can be notable for communities being organized in Notion.

“Sorry, that request was too large. Try import instead?”

Pasting content from the clipboard sometimes leads to this message. So what is the maximum amount of plain text that Notion can accept from the clipboard?

👉 TL;DR: 750kb

A pretty technical explanation from Notion Engineering:

It’s a bit complicated, but basically we have a limit on the maximum body size to ensure that clients don’t submit massive records containing unrenderable content that might cripple our servers or clients. If we lift the 750kb payload limit, we need to introduce some other kind of validation that ensures this can’t happen, which hasn’t been done yet.

What are the maximum number of steps I can run in a single Button automation?

In Notions Button automations you can add up to 100 steps that will be run when the Button is pressed in order. When buttons shipped, the limit was 10, but this was quickly increased due to popular demand.

If you want to learn about Notion Button automations, check out my video “Notion Buttons: A Big Step Towards Internal Automation in Notion“.

How many times can I reference a Property in a Formula?

You can mention the same property up to 100 times in formulas. After that the prop("Name") will stop being converted to Property Tokens and will fail.

How many automations can I have in databases?

There are limits for the number of automations in a database. It’s dependent on the plan type your workspace is on. For Free plan that limit is 15 per database. Paid plans have a maximum of 100 per database, which matches the Button automation step limit.

API Limitations

Rate Limits

According to the Developer docs:

The rate limit for incoming requests per integration is an average of three requests per second. Some bursts beyond the average rate are allowed.

This means if you’re doing a load of successive requests, you may have to back off or throttle requests to the API so they don’t fail.

In March of 2022, a Notion Engineer shared the following in the Notion Devs Slack:

The rate limit is 2700 calls every 15 minutes per token.

So that’s where we get that “average of three requests per second”:

2,700 / (15 x 60) = 3

This means that you could do 1,000 calls over just a couple seconds and then stop and you’d be within limits for at least 15 minutes. Typically this works fine for reading content via the API, but you may run into some issues when updating content.

I use the async-sema node package to create rate limiters when accessing data in bulk. In my notion-api-examples repository, you can find helpers you could use to perform bulk actions with built-in rate limiting.

Here’s a small and rather contrived example of using the helpers to update all the icons of all pages in a database. By default I use aync-sema RateLimit to limit to 1 request every 2 seconds. Though Notion says it’s an average of 3 requests-per-second (rps), with edit requests, I find it takes a bit for the updates to “settle” in the parent database, so it’s best to throttle back a bit here. YMMV.

In a real-world application, I’d probably dump these updates into a backend job queue with throttling enabled and if any 429 Too Many Requests errors are returned from the Notion API, re-enqueue them to run at a later time.

A complex topic, to be sure!

Property size limits

This is a well-documented limit you can find on the same page as the request limits above. One example of such a limit is a Text property can only be up to 2,000 characters. There is no limit on length in the Notion app itself, as documented in the Developer’s Docs:

These limits apply to requests sent to Notion’s API only. There are different limits on the number of relations and people mentions in responses returned by the API.

Rollup not accurate? Know about property reference limits.

👉 TL;DR: only 25 references are returned with properties when fetched with Page API

When you retrieve a Page via the API, some but not all of its Property references will be returned. The max is 25 references. This applies to Relations as well as “@-references” (People, Page Mentions, etc) in Text properties. For example, if you mention 30 people in a Text field or have 100 Pages related to the Page, you will only get the first 25 of each of these.

This causes problems with Rollup data because the Rollup’s calculation will be based on only 25 of the referenced Page’s value.

In order to get the entire set, you must query the Property itself using the Retrieve Property endpoint. Notion’s API will allow you to paginate through the properties, so in order to get the full accurate data for a Rollup that has 100 references, you’ll need to make at minimum 4 requests and then perform the calculation yourself with code.

You can specify the page_size in paginated resources and the max is 100. So for our contrived example, we could make one request with page_size=100 to get an accurate Rollup value.

I recorded a demo of this dynamic for a fellow developer last year:

Demoing the Notion API’s property reference limits

Limits when updating Relations via the API

👉 TL;DR: you can only relate up to 100 items via the API

Fellow hacker Nick Janes brought this API limit to my attention:

Updating a relation property of a Database Page is done by supplying the entire list of Relations. There is no way to “detach” or “append” a related page via the API. When doing so, you can only add 100 related pages. So, if you have 120 related pages, the last 20 have to be attached manually via the application.

Formula maximum depth

👉 TL;DR: 10 referenced tables

This one is documented under the Retrieve a page property item limitations where it says:

formula property values that exceed have or exceed depth of 10 referenced tables, the API will return a “Formula depth” error as a validation_error.

As a workaround, you can retrieve the formula property object from the Retrieve a Database endpoint and use the formula expression to compute the value of more complex formulas.

What this is saying is basically that you can fetch all the the data, but the value of the formula sent back from the API may not be accurate. In this case, it seems you will have to run a similar snippet of code on your end to calculate the results (”use the formula expression”).

Block types that are unsupported or have limited support

There are a number of limitations to feature-support in the API. Here are the ones that I’m excited to see ship in the future:

Linked Views (unsupported)
Link Previews (unsupported)
Status (limited) — you cannot create Status properties, only read and update

Database property creation limits

There’s currently no way to specify the order of Properties in a Database. They will be added to the bottom of the existing Property list in alphabetical order upon creation.
There’s no way to configure the “Show/Hide” setting of a Property via the API.

Block limitations

For blocks that allow children, the Notion API allows two levels of nesting in a single request. This means if you have a complex page to create with further nesting, you’ll have to keep references to the parent blocks and recursively create the children until the hierarchy is finished. This can take a lot of time and many requests.
Blocks cannot be “Moved” via the API. You will have to copy the contents of the Block and create a new Block with the same child content in a different Parent Block, then delete the original Block.

Unsupported Rollup Aggregations

This one is documented here, stating:

Due to the encoded cursor nature of computing rollup values, a subset of aggregation types are not supported. Instead the endpoint returns a list of all property_item objects for the following rollup aggregations…

One of the examples it gives is show_unique (Show unique values). This one’s a little hard to understand, but what I take this to mean is that it’s not actually going to show you the unique items for the Property, it will give you all of them.

In short: it seems like it’s on you to solve for uniqueness!

Other limitations

The API currently does not support file uploads.
The Comments API has some well-documented limitations in the Working with comments guide.

Good luck and keep pushin’.

[*For full disclosure, I’m a Notion Partner, so when you sign up with my link, you also help support me and my content!]

Share This Post

Get Notion tips in your inbox

When you sign up, you’ll get tips, perspectives, and opinions on how you can better use Notion. Plus you’ll get a steady drip of Notion updates, videos, interviews, and resources from the Notion Mastery team.

Pushing Notion to the Limits

Introduction

Table of Contents

Plan Limitations