Values and request size

These limits apply to one request, not to how much a value can hold. Text typed in the app can be longer.

Write requests

Target	Limit	Over the limit
Request body	500 KB (512,000 bytes)	400 `validation_error` `Request body is too large. The maximum size is 512000 bytes.`
One value write	768,000 bytes in storage format	400 `validation_error` `The page properties are too large.`
Characters in one `title` or `rich_text` item	2,000 (UTF-16 code units)	400 `validation_error`
Items in `title` or `rich_text`	100	400 `validation_error`
Items in `multi_select`, `people`, `relation`, `files`	100	400 `validation_error`
`url`	2,000 characters	400 `validation_error`
`email`, `phone_number`	100 characters	400 `validation_error`
Option name	2,000 characters, no commas	400 `validation_error`
Options per property	1,000	400 `Invalid select option for property: ...`
File name (`external`)	100 characters	400 `validation_error`
External file or cover URL	2,048 characters	400 `validation_error`

The 768,000-byte limit counts formatting data after conversion to storage format, so a heavily formatted value can exceed it even when the request body is under 500 KB. Item limits return these messages:

body failed validation: body.properties.Notes.rich_text[0].text.content.length should be ≤ `2000`, instead was `2001`.
body failed validation: body.properties.Notes.rich_text.length should be ≤ `100`, instead was `101`.

Long text

Bottari returns rich_text and title arrays as items of up to 2,000 characters. Emoji are never split, so some items are shorter.

Text	Item lengths returned
Empty	No items (`[]`)
Short	One item
5,001 characters (1,999 + an emoji + 3,000)	`[1999, 2000, 1002]`
Written as 100 items of 2,000 characters	100 items
Written as several short items with the same formatting	Merged, then split every 2,000 characters

Block rich_text and comments work the same way. A 2,500-character comment returns [2000, 500].

Reading only rich_text[0] returns just the first 2,000 characters. Join every item.

const text = property.rich_text.map((item) => item.plain_text).join("");

Write back what you read

You can write long text back as you read it, because the items are already within 2,000 characters. Text over 200,000 UTF-16 code units has more than 100 items, so writing it back as read returns 400. The API can’t write that much at once, so this only happens with text from another path such as typing in the app.

Write new long text

Split new long text into items of up to 2,000 characters. Don’t split a surrogate pair such as an emoji.

function toItems(text, size = 2000) {
  const out = [];
  for (let i = 0; i < text.length; ) {
    let end = Math.min(i + size, text.length);
    const last = text.charCodeAt(end - 1);
    if (end < text.length && last >= 0xd800 && last <= 0xdbff) end -= 1;
    out.push({ text: { content: text.slice(i, end) } });
    i = end;
  }
  return out;
}

Read responses

Target	Limit	How to read everything
`page_size` in lists	1 to 100, default 100	Pass `start_cursor` to read the next set.
`relation` in a row response	25, with `has_more`	Retrieve a property value
Original rollup values in a row response	Over 25 returns `type: "unsupported"`	Retrieve a property value
`people`, `title`, `rich_text` in a row response	No limit	Everything is included.
`unknown_block_ids` in Markdown	100	Read them through the block API.
Signed URLs for files, icons, covers	Expire after 1 hour (`expiry_time`)	Read again to get a new URL.

Writing back a relation with has_more: true as read drops everything after the first 25, because a write replaces the whole value. Read all of it first.

Filters and sorts

Target	Limit
`and`/`or` nesting	2 levels
Items in one `and` or `or` array	100
Conditions in one request	1,000 in total
`sorts` items	100
Name array for `select`, `status`, `multi_select`	100

Integrations and webhooks

Target	Limit
Integrations per team	25
Integration name	80 characters
Creating integrations, regenerating tokens, creating subscriptions	10 per hour per team, combined
Webhook subscriptions per integration	1
Resending a verification token	10 per hour per subscription
Webhook receiving address	2,048 characters

Block limit

When a team reaches its block limit, creating a row returns 403 restricted_resource This workspace has reached its block limit.

Get started

Import data

Authentication and access

Limits

Webhooks

Write requests

Long text

Write back what you read

Write new long text

Read responses

Filters and sorts

Integrations and webhooks

Block limit

​Write requests

​Long text

​Write back what you read

​Write new long text

​Read responses

​Filters and sorts

​Integrations and webhooks

​Block limit

Write requests

Long text

Write back what you read

Write new long text

Read responses

Filters and sorts

Integrations and webhooks

Block limit