Workspace block limits

The REST API now enforces the existing Free workspace block limit for the connections described below.

Scope

Free workspaces with more than one member have a limit of 1,000 lifetime blocks. Paid workspaces and single-member Free workspaces have unlimited blocks. Guests do not count as members. Deleting blocks does not restore capacity. See Understanding block usage. The limit applies to internal connections and OAuth connections restricted to selected workspaces. It does not apply to personal access tokens or OAuth connections that can be installed in any workspace. Notion MCP has a separate enforcement policy.

Creation and grace period

The limit is shared across the workspace, not assigned to each connection. The write that first reaches the limit succeeds and starts the existing three-day grace period. Creation remains available during grace. API enforcement does not restart an expired grace period. After grace expires, requests that create blocks fail. Reads, deletes, and edits that do not create blocks remain available. Template jobs check the limit again when they run, so a queued template can fail after the request that scheduled it returned a success.

Background templates

A successful create or update response does not guarantee that a queued template will finish. The job checks the limit again before copying content and before each content write. If the workspace becomes blocked, the job stops without retrying the plan restriction. The target page is kept, but it may be blank or contain only part of the template. When replacing content, the original content is removed only after the template succeeds. There is no template-failure webhook or public job-status endpoint. Set a timeout when waiting for template content, then retrieve the page’s block children to check the result. Do not automatically reapply a template to a partially populated page: that can duplicate content. Ask a workspace owner to check block usage before retrying.

Affected endpoints

A request fails if it would create blocks. Requests that do not create blocks remain available.

Endpoint	Behavior after grace expires
Create a page	Fails. The page itself is a block.
Create a meeting note	Fails. Creates a meeting notes block and its child blocks.
Create a database	Fails. The database is a block.
Create a database (deprecated)	Fails. API versions before `2025-09-03` create a database block with its data source.
Create a data source	Still works. API versions `2025-09-03` and later add a data source to an existing database without creating a block.
Append block children	Fails. Every appended child is a block.
Update page markdown	Fails when the markdown adds blocks.
Update a page	Fails when the update adds blocks, such as applying a template. Title and property edits still work.
Update a block	Fails when the update adds blocks.
Create a view	Fails when `create_database` adds a linked database block. A new view tab on an existing database still works.
Create a comment	Fails when an attachment adds a block. A comment without attachments still works.

Error response

Blocked writes return HTTP 403 with the restricted_resource code:

{
  "object": "error",
  "status": 403,
  "code": "restricted_resource",
  "message": "This workspace has used all of its free blocks. Upgrade its plan in Notion to create more content. Learn more: https://www.notion.com/help/understanding-block-usage",
  "additional_data": {
    "block_limit": "block_creation"
  }
}

This is a plan limit, not a request rate limit. Retrying the same write without a workspace change will not resolve it. A workspace owner can upgrade in Notion. Creation is also available when the Free workspace has only one member. Other permission failures also use restricted_resource. The additional_data.block_limit field identifies this limit without relying on message text. See Status codes and Request limits.

Notion API

Objects

Endpoints

Webhook events

Workspace block limits

Scope

Creation and grace period

Background templates

Affected endpoints

Error response

​Scope

​Creation and grace period

​Background templates

​Affected endpoints

​Error response

Scope

Creation and grace period

Background templates

Affected endpoints

Error response