Docs
Connections

Notion

Create a read-only Notion connection, share databases with it, and read data source rows as datasets, with Notion's limits and personal data rules.

A Notion connection reads the rows of the databases you share with it. In Notion, the thing you create for this is called a connection (Notion used to call it an integration). Xentropy only reads: it never changes your pages.

Availability

Notion is not yet generally available on xentropy.ai. Contact support@xentropy.ai to request access. Until it is enabled for your account, it does not appear in the catalogue and its reads fail with PROVIDER_DISABLED.

Create a Notion connection

In Notion, open Settings → Connections → Develop or manage connections, and create an internal connection for your workspace.
Under Capabilities, keep Read content and turn off Update content and Insert content. Xentropy needs no user information.
Open the connection's Configuration tab and copy its secret (it starts with ntn_).
Share each database you want to read: open the database, choose ••• → Connections and add your connection. A connection sees only what is shared with it.

Notion has no scopes to grant: the Read content capability and the databases you share decide what the connection can read.

Set up the connection

Open Connections, choose New connection, then Notion.
Name the connection and paste the secret.
Choose Test connection. The test checks the secret (stage auth) and lists every data source shared with the connection.
Pick the data sources to read (at least one), then choose Save connection.
Open the connection's resources, pick a data source and its fields, preview 100 rows and save a dataset.

A Notion database can hold more than one data source. Each data source is listed and read on its own. Up to 500 data sources are listed.

Notion needs no IP allowlist: Xentropy connects only to api.notion.com.

Fields

Every row has page_id, url, created_time and last_edited_time, plus one field per property:

Notion propertyDataset type
Title, textstring, cut at 10,000 characters (VALUE_TRUNCATED warning)
Numbernumber
Select, statusstring (the option name)
Multi-select, relation, filesJSON list, or comma-separated text
Datedate, or datetime when values have a time, plus a <name>_end field
Checkboxboolean
People, created by, last edited bynames. Emails are separate personal data fields
Formula, rollupby the result type
URL, unique ID, placestring
Email, phonestring, personal data
Created time, last edited timedatetime

Button, verification and unknown property types are not read; the field picker lists them. A formula or rollup that Notion cannot compute for the API becomes empty, with a VALUE_UNSUPPORTED warning. File links are never stored: Notion signs them and they expire.

When a value no longer fits its type

A dataset keeps the field types it was saved with. Dates, formulas and rollups take their type from the values seen when you saved the dataset. If a later value does not fit, for example text in a field saved as a number, the read fails with TYPE_MISMATCH and names the field and row. Describe the data source again and save the dataset with the new field type. A date without a time in a datetime field is read as midnight UTC.

Personal data

Email and phone properties, and people emails (on people, created by and last edited by properties), are personal data. They are marked Personal data in the field picker and are off by default.

  • If you select one, the dataset is marked as containing personal data (containsPii). The API and agents must confirm this with containsPii: true, otherwise the selection is refused.

Limits

LimitValue
Rows per read50,000, and at most 10,000 from Notion (see below)
Fields per dataset100
Pages per readFree 100, Pro 600 (100 rows per page)
Request rate2.5 requests per second per connection secret
Text per value10,000 characters
Related pages per relation value25
Data sources listed500
Read deadline30 s interactive, 300 s scheduled
  • Notion's 10,000-row cap. Notion returns at most 10,000 rows for one query. When a data source has more, the read fails with SOURCE_RESULT_LIMIT. Xentropy never treats such a read as complete. Add a filter in Notion, or split the data source.
  • Free plan. At 100 rows per page, Free reads stop at about 10,000 rows with LIMIT_EXCEEDED.
  • Relations. Notion returns up to 25 related pages per value. When a value has more, the read carries a RELATION_TRUNCATED warning.
  • People. Notion returns at most 25 people per value and does not say when it cut the list, so Xentropy cannot warn about it.
  • Notion reads are paced at about 2.5 requests per second, so large data sources take a while. Xentropy waits for Notion's Retry-After when Notion is busy.

Errors

CodeCauseWhat to do
PROVIDER_ACCESS_DENIED, stage authThe secret was rejectedCopy the secret again, then replace the configuration
NOT_FOUNDThe database is no longer shared with the connectionIn Notion, open the database, choose ••• → Connections and add the connection again
SOURCE_RESULT_LIMITMore than 10,000 matching rows, Notion's limit for one queryAdd a filter in Notion, or split the data source
LIMIT_EXCEEDEDMore than the plan's pages, or 50,000 rowsUse a smaller data source, or upgrade to Pro
RATE_LIMITEDNotion's rate limit or overload. details.retryAt says when to retryRetry after retryAt
TYPE_MISMATCHA value does not fit the field type the dataset was saved withDescribe the data source again and save the dataset
PERMISSION_DENIEDThe data source is not selected on the connectionSelect it, or replace the configuration
VALIDATION_FAILEDPersonal data selected without containsPii, or an invalid idFix the selection
WarningMeaning
RELATION_TRUNCATEDA relation value has more than 25 related pages; only 25 were read
VALUE_TRUNCATEDText longer than 10,000 characters was cut
VALUE_UNSUPPORTEDNotion could not compute a formula or rollup value for the API; it is empty

On this page