Skip to main content
Notion is Available Now as a source-only connector. Protected runtime health reports dependency and configuration readiness as diagnostics. It reads content shared with a Notion internal integration, discovers modern Notion data sources, previews rows, stages them through dlt, applies published SQL transformations, and delivers the result to a supported destination. MantrixFlow never writes to Notion.

​
Supported resources

Notion separates a database container from the data sources inside that database. MantrixFlow exposes each discovered data source as its own stable stream so renaming a database or data source does not change pipeline identity. A data-source stream has this form:
Its DuckDB staging relation is:
The row payload preserves Notion page metadata and properties, including id, created_time, last_edited_time, in_trash, url, parent, properties, created_by, and last_edited_by. Property values remain JSON because every Notion data source can define a different schema.

​
Before you begin

  1. Open Notion integrations.
  2. Create an internal integration for the workspace that MantrixFlow will read.
  3. Enable read-content access and copy the internal integration token.
  4. Open each page or database that should be visible to MantrixFlow.
  5. Use Connections in Notion to share that content with the integration.
Creating an integration does not automatically grant access to workspace content. Notion returns only pages and databases explicitly shared with the integration or inherited through a shared parent page.
Treat the integration token like a password. MantrixFlow encrypts it at rest, masks it after saving, and removes it from agent-visible configuration and sanitized errors.

​
Create the source connection

  1. Open Connections in your MantrixFlow workspace.
  2. Click + New Connection and select Source.
  3. Select Notion.
  4. Enter a descriptive connection name and the internal integration token.
  5. Click Test Connection. MantrixFlow validates the token against the authenticated Notion bot identity.
  6. Save the connection after the test succeeds.
If a Notion connection test fails, review the protected runtime diagnostic for the exact dependency or configuration reason, then retry after correcting it.

​
Discover and select data sources

  1. Create or open a pipeline that uses the Notion connection.
  2. Open Source and click Discover catalog.
  3. Expand the database groups and select the required data-source streams.
  4. Choose Full Table or Incremental for each selected data source.
  5. Preview representative rows.
  6. Save the stream settings.
Discovery uses Notion Search only to find content visible to the integration. MantrixFlow then retrieves each data source directly to obtain authoritative schema and parent-database metadata. Search is never used to extract the rows for a pipeline run. Notion Search indexing can be delayed. After sharing new content, wait briefly and refresh discovery if it does not appear immediately.

​
Full Table and Incremental

Full Table reads every visible row from the selected data source and replaces its staging resource for the run. Incremental uses dlt merge semantics with id as the merge key and last_edited_time as the cursor. The request uses an inclusive timestamp boundary so records sharing the last checkpoint timestamp are reread safely and deduplicated by primary key. Checkpoint state advances only after successful staging and delivery. A failed or partial run does not commit the candidate Notion cursor. Incremental extraction is scheduled polling, not CDC. Deleted or permission- revoked content may require a periodic Full Table reconciliation depending on the destination model.

​
Transform Notion properties

Notion properties are stored in the properties JSON object. Inspect a preview to confirm each property’s type before writing SQL. Example model for a task data source:
Replace <id> with the staging relation shown in the transformation editor. Use id as the destination Upsert key unless the published model produces a different stable, unique key.

​
API behavior and safety limits

The connector uses the Notion 2026-03-11 API contract and queries rows through the modern data-source endpoint. Requests are limited to an average of three per second per connection. 429 responses honor Retry-After; transient server failures use bounded exponential retry. Notion data-source queries can return at most 10,000 results for one query. If Notion reports an incomplete request or the connector reaches that cap, MantrixFlow fails the run instead of reporting partial data as complete. Split very large operational datasets into smaller Notion data sources before syncing them.

​
Multi-data-source databases

A single Notion database can contain multiple data sources. Discovery presents each one independently. Select the exact data source you want to sync. Older saved configurations that contain only a database ID are resolved automatically when the database has exactly one data source. When it has more than one, MantrixFlow asks for an explicit data-source selection rather than guessing.

​
Verify a run

After starting the pipeline, open Runs and confirm:
  • the expected notion.data_source_... streams are listed;
  • Rows failed is 0;
  • the destination shows the expected target tables;
  • direct destination counts match the run result; and
  • a second Incremental run updates edited pages without duplicating id.

​
Limitations

  • Notion is source-only.
  • Authentication uses an internal integration token; OAuth is not available.
  • Only content shared with the integration can be discovered or read.
  • Search discovery can lag after permission changes.
  • Data-source queries reaching 10,000 results fail safely; automatic time-window partitioning is not implemented.
  • Rich page properties remain nested JSON and may need SQL extraction.
  • Explicit page-content and nested-block resources are not selectable in the current self-serve catalog.
  • The connector does not provide realtime CDC.

​
Troubleshooting

Next, review Sync modes and Incremental sync.