Skip to main content

Notion

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Connector type (beta)
Available Data replicationAvailable Agent(learn more)
Support Level
Airbyte
Connector Version
4.0.26 (last updated 7 days ago)
Sync Success Rate
High
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
6e00b415-b02e-4160-bf02-58176a0ae687

This page contains the setup guide and reference information for the Notion source connector.

Prerequisites​

  • Access to a Notion workspace
  • To authenticate with an access token, or with your own OAuth connection in Airbyte Open Source, you must be a Workspace Owner in Notion so you can create a connection

Setup guide​

To authenticate the Notion source connector, use one of the following methods:

  • OAuth2.0 authorization (recommended for Airbyte Cloud)
  • Access Token

Notion calls the apps that access its API connections. You manage them in the Notion Developer portal. For more detail, see Notion's internal connections and public connections guides.

note

For Airbyte Cloud users: If you use OAuth2.0 authorization in Airbyte Cloud, you don't need to create a connection in Notion. Skip to setting up the connector in Airbyte.

Step 1: Create a connection in Notion and set capabilities​

  1. Open the Notion Developer portal. In the Build section of the sidebar, select Internal connections.

  2. Click Create a new connection, enter a name, and choose the workspace you want to sync.

  3. Open the connection's Configuration tab and enable the following capabilities based on the streams you want to sync:

    • Read content: Required for all connections.
    • Read comments: Required for the Comments stream.
    • Read user information (with or without email addresses): Required for the Users stream.

Step 2: Share pages and get your credentials​

Access Token (Cloud and Open Source)​

The connector only syncs pages and data sources that you share with your connection. Sharing a page also shares all of its child pages.

  1. Share the pages you want to sync with your connection. Use either method:
    • In the Developer portal, open your connection, click the Content access tab, click Edit access, and select the pages and databases to share.
    • In Notion, open a page, click the ••• menu in the top-right corner, select Connections, click + Add connection, and choose your connection.
  2. In the connection's Configuration tab, copy the API token. Then continue to setting up the connector in Airbyte.

OAuth2.0 (Open Source only)​

To use OAuth2.0 in Airbyte Open Source, create a public connection instead of an internal connection, then complete Notion's OAuth flow to get an access token.

  1. In the Developer portal, in the Build section of the sidebar, select Public connections, then click Create new connection.
  2. Fill in the required fields, including a redirect URI, and enable the capabilities listed in Step 1.
  3. In the connection's Configuration tab, copy the OAuth client ID and OAuth client secret.
  4. Use the connection's authorization URL to choose the pages to share and exchange the returned code for an access token. Notion's authorization guide explains each step. When you have your client ID, client secret, and access token, continue to the next step.

Step 3: Set up the Notion connector in Airbyte​

  1. Log in to your Airbyte Cloud account, or navigate to your Airbyte Open Source dashboard.
  2. In the left navigation bar, click Sources. In the top-right corner, click New source.
  3. Find and select Notion from the list of available sources.
  4. Enter a Source name of your choosing.
  5. Choose the method of authentication from the dropdown menu:

Authentication for Airbyte Cloud​

  • OAuth2.0 (Recommended): Click Authenticate your Notion account. When the popup appears, click Select pages. Check the pages you want to give Airbyte access to, and click Allow access.
  • Access Token: Paste the API token from your internal connection's Configuration tab.

Authentication for Airbyte Open Source​

  • Access Token: Paste the API token from your internal connection's Configuration tab.
  • OAuth2.0: Paste the client ID, client secret, and access token from your public connection.
  1. (Optional) Enter a Start Date in UTC, in the format YYYY-MM-DDTHH:mm:ss.SSSZ. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date.
  2. (Optional) Set Number of concurrent workers to control how many requests the connector makes in parallel. The default is 3 and the maximum is 10. For guidance, see Performance considerations.
  3. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Notion source connector supports the following sync modes:

StreamFull Refresh (Overwrite/Append)Incremental (Append/Append + Deduped)
Blocks✓✓
Comments✓✓
Data Sources✓✓
Pages✓✓
Users✓

Incremental streams use the last_edited_time field as the cursor and filter records on the client side. On each sync, the connector reads records from Notion and only emits records edited since the last sync.

Supported streams​

The Notion source connector supports the following streams:

  • Blocks: Retrieves content blocks for all synced pages, including recursively nested child blocks up to 30 levels deep. Block types child_page, child_database, and ai_block are excluded.
  • Comments: Retrieves un-resolved comments on all synced pages. Requires the Read comments capability.
  • Data Sources: Retrieves all data sources shared with your connection, using the Search endpoint. In Notion API version 2025-09-03, a data source represents a structured table that contains pages and properties, previously called a "database." This stream replaces the former Databases stream as of v4.0.0. For details on migrating, see the Notion migration guide.
  • Pages: Retrieves all pages shared with your connection, using the Search endpoint.
  • Users: Retrieves users in the workspace, including bots. Notion doesn't return guests from this endpoint. Requires the Read user information capability.

Record format​

The connector reshapes some fields so they have a consistent structure in your destination:

  • Pages and Data Sources: Notion returns properties as an object keyed by property name. The connector converts it to an array of objects, each with a name field (the property name) and a value field (the property object Notion returned).
  • Users: For bot users, Notion stores owner details under a key that matches the owner type, such as bot.owner.workspace or bot.owner.user. The connector moves these details to bot.owner.info. The bot.owner.type field still tells you the owner type.

Performance considerations​

Notion rate limits each connection to an average of three requests per second on most plans, and ten requests per second on Business and Enterprise plans. Notion also enforces a separate limit shared across all connections in a workspace. When the connector receives an HTTP 429 response, it waits for the time in the Retry-After header and retries the request. Rate-limited requests don't count toward the maximum retry limit, so syncs continue until the rate limit clears. For more details, see Notion's request limits documentation.

The connector sends requests in parallel. Use the Number of concurrent workers setting (1 to 10, default 3) to control parallelism. More workers can speed up large syncs, but make it more likely that the connector hits Notion's rate limits.

The Blocks stream recursively fetches child blocks up to 30 levels deep. Pages with deeply nested content can generate a large number of API requests, which can slow down syncs for workspaces with complex page structures. If Notion returns a 404 error because a block isn't shared with your connection, the connector skips that block instead of failing the sync.

Troubleshooting​

Users stream fails with a permission error​

If the Users stream fails with the message "Notion integration lacks read user information for the Users stream," your connection doesn't have the Read user information capability. Open your connection in the Notion Developer portal and enable Read user information in the Configuration tab. If you don't need user data, disable the Users stream in your Airbyte connection instead.

Notion personal access tokens can't list workspace users. If you authenticate with a personal access token instead of an internal connection's API token, disable the Users stream.

Pages or blocks are missing​

The connector only syncs content that you share with your connection. If pages, data sources, or blocks are missing, confirm that you shared the parent page with your connection, or that you selected the page during the OAuth flow.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
object
credentials
integer
num_workers
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
4.0.282026-10-1388131Replace custom record transformations for the users, pages and data_sources streams with declarative components (no change to record output)
4.0.272026-10-1388718Update dependencies
4.0.262026-10-0687944Update dependencies
4.0.252026-09-2987242Update dependencies
4.0.242026-09-2286721Update dependencies
4.0.232026-09-1586135Update dependencies
4.0.222026-09-0885579Update dependencies
4.0.212026-08-1884680Update dependencies
4.0.202026-08-1184017Update dependencies
4.0.192026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
4.0.182026-07-2883183Roll Cloud back to 4.0.16 — 4.0.17 is built on SDM 7.23.7, which breaks bundled custom components
4.0.172026-07-2883001Update dependencies
4.0.162026-07-2182506Update dependencies
4.0.152026-07-1481929Update dependencies
4.0.142026-06-3081166Update dependencies
4.0.132026-06-2380566Update dependencies
4.0.122026-06-1679948Update dependencies
4.0.112026-06-0979397Update dependencies
4.0.102026-06-0278821Update dependencies
4.0.92026-06-0178048Improve the permission error message for the Users stream when the Notion integration lacks user information capabilities.
4.0.82026-06-0178543Set final default concurrency to 3 with configurable worker count
4.0.8-rc.52026-05-2878467Remove Notion API budget while keeping configurable worker count defaulted to 5
4.0.8-rc.42026-05-2678433Reduce default concurrency to 4 while preserving configurable worker count and Notion API budget
4.0.8-rc.32026-05-2278343Revert default concurrency to 5, add configurable worker count, and enforce Notion API budget
4.0.8-rc.22026-05-1978274Increase default_concurrency to 6 for concurrency tuning iteration 2
4.0.8-rc.12026-05-1878149Start concurrency tuning rollout
4.0.72026-04-2877340Update dependencies
4.0.62026-04-2176681Update dependencies
4.0.52026-04-0175577Add oauth_connector_input_specification for declarative OAuth
4.0.42026-03-3175747Update dependencies
4.0.32026-03-3075603Fix 429 status code mapping from RETRY to RATE_LIMITED for improved rate limit handling and observability
4.0.22026-03-2375290Update v4.0.0 upgrade deadline to 2026-04-10
4.0.12026-03-1074616Update dependencies
4.0.02026-02-2574017Migrate to Notion API version 2025-09-03: replace databases stream with data_sources, update page parent references, and add new schema fields
3.3.142026-02-2473856Update dependencies
3.3.132026-02-1073032Update dependencies
3.3.122026-02-0972925Add client-side incremental filtering to blocks stream RecordFilter
3.3.112026-01-2071943Update dependencies
3.3.102026-01-1471602Update dependencies
3.3.92025-12-1870534Update dependencies
3.3.82025-11-2569853Update dependencies
3.3.72025-11-2469780Fix bug in current_block_depth
3.3.62025-11-1869375Update dependencies
3.3.52025-10-2968750Update dependencies
3.3.42025-10-2168399Update dependencies
3.3.32025-10-1467801Update dependencies
3.3.22025-10-0767422Update dependencies
3.3.12025-09-3066927Update dependencies
3.3.02025-09-2966734Promoting release candidate 3.3.0-rc.1 to a main version.
3.3.0-rc.12025-09-2566532Migrate to manifest-only.
3.2.02025-09-2566695Promoting release candidate 3.2.0-rc.4 to a main version.
3.2.0-rc.42025-09-2466664Handle 404 error and add sequence_number for blocks stream
3.2.0-rc.32025-09-1966539Add default start date if not provided in the config to custom component
3.2.0-rc.22025-09-1966530Add default start date if not provided in the config
3.2.0-rc.12025-09-1866191Migrate Blocks stream to manifest.
3.1.02025-07-3055725Add sequence_number to fetched Notion blocks
3.0.162025-07-2864102Promoting release candidate 3.0.16-rc.1 to a main version.
3.0.16-rc.12025-07-2163368Migrate to CDK V6
3.0.152025-07-1963382Update dependencies
3.0.142025-07-1263213Update dependencies
3.0.132025-07-0562609Update dependencies
3.0.122025-06-2462033Add "in_trash" field in Notion "Pages" endpoint schema
3.0.112025-06-2862356Update dependencies
3.0.102025-06-2161902Update dependencies
3.0.92025-06-1461602Update dependencies
3.0.82025-06-0752290Update dependencies
3.0.72025-01-1143832Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
3.0.62024-06-2540498Fix Pydantic error - add missing type annotation for max_cursor_time
3.0.52024-06-0438871Refactor: use client_side_incremental feature
3.0.42024-06-0638798Implement CheckpointMixin for state handling
3.0.32024-06-0639204[autopull] Upgrade base image to v1.2.2
3.0.22024-05-2038266Replace AirbyteLogger with logging.Logger
3.0.12024-04-2436653Schema descriptions and CDK 0.80.0
3.0.02024-04-1235974Migrate to low-code CDK (python CDK for Blocks stream)
2.2.02024-04-0836890Unpin CDK version
2.1.02024-02-1935409Update users stream schema with bot type info fields and block schema with mention type info fields.
2.0.92024-02-1235155Manage dependencies with Poetry.
2.0.82023-11-0131899Fix table_row.cells property in Blocks stream
2.0.72023-10-3132004Reduce page_size on 504 errors
2.0.62023-10-2531825Increase max_retries on retryable errors
2.0.52023-10-2331742Add 'synced_block' property to Blocks schema
2.0.42023-10-1931625Fix check_connection method
2.0.32023-10-1931612Add exponential backoff for 500 errors
2.0.22023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
2.0.12023-10-1731507Add start_date validation checks
2.0.02023-10-0930587Source-wide schema update
1.3.02023-10-0930324Add Comments stream
1.2.22023-10-0930780Update Start Date in config to optional field
1.2.12023-10-0830750Add availability strategy
1.2.02023-10-0431053Add undeclared fields for blocks and pages streams
1.1.22023-08-3029999Update error handling during connection check
1.1.12023-06-1426535Migrate from deprecated authSpecification to advancedAuth
1.1.02023-06-0827170Fix typo in blocks schema
1.0.92023-06-0827062Skip streams with invalid_start_cursor error
1.0.82023-06-0727073Add empty results handling for stream Blocks
1.0.72023-06-0627060Add skipping 404 error in Blocks stream
1.0.62023-05-1826286Add parent field to Blocks stream
1.0.52023-05-0125709Fixed ai_block is unsupported by API issue, while fetching Blocks stream
1.0.42023-04-1125041Improve error handling for API /search
1.0.32023-03-0222931Specified date formatting in specification
1.0.22023-02-2423437Add retry for 400 error (validation_error)
1.0.12023-01-2722018Set AvailabilityStrategy for streams explicitly to None
1.0.02022-12-1920639Fix Pages stream schema
0.1.102022-09-2817298Use "Retry-After" header for backoff
0.1.92022-09-1616799Migrate to per-stream state
0.1.82022-09-0516272Update spec description to include working timestamp example
0.1.72022-07-2615042Update additionalProperties field to true from shared schemas
0.1.62022-07-2114924Remove additionalProperties field from schemas and spec
0.1.52022-07-1414706Added OAuth2.0 authentication
0.1.42022-07-0714505Fixed bug when normalization didn't run through
0.1.32022-04-2211452Use pagination for User stream
0.1.22022-01-119084Fix documentation URL
0.1.12021-12-309207Update connector fields title/description
0.1.02021-10-177092Initial Release
Was this page helpful?