Advanced Analytica Advanced Analytica: IBOM
← All connectors
Notion logo

Source connector

Notion

Set up Notion as a source and move its data into your chosen destination.

Version 4.0.33 certified generally available

Notion

Set up the Notion source connector and find its reference information on this page.

Prerequisites

  • Access to a Notion workspace
  • You must own the workspace to create a Notion integration

Setup guide

Authenticate the Notion source connector using one of these two methods:

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

:::note For Airbyte Cloud users: OAuth2.0 authorization significantly simplifies your Notion setup. In Airbyte Cloud, you do not need to create and configure a new Notion integration. You can proceed directly to setting up the connector in Airbyte. :::

The quick guide below explains how to create a Notion integration. For more detail, context or setup help, refer to the official Notion documentation.

Step 1: Create an integration and set capabilities

  1. Log in to your Notion workspace and open the My integrations page. Select New integration.

:::note You must own the Notion workspace to create a new integration for it. :::

  1. Enter a Name for your integration. Select the correct workspace from the Associated workspace dropdown menu, then click Submit.
  2. Select Capabilities in the navbar. Choose these capabilities based on your use case:

Step 2: Share pages and get credentials

Access Token (Cloud and Open Source)

When authenticating with an Access Token, manually share each page you want to sync with Airbyte.

  1. Open the page or pages you want to share with Airbyte. Click the ••• menu at the top right. Select Add connections, then choose the integration you created in Step 1.
  2. After selecting every page, open the Secrets tab on your Notion integration’s page. Copy the Access Token, then proceed to setting up the connector in Airbyte.

OAuth2.0 (Open Source only)

To authenticate via OAuth2.0 for Airbyte Open Source, make your integration public. You also need your Client ID, Client Secret and Access Token.

  1. Open the Distribution tab on your integration page. Toggle the switch to make the integration public.
  2. Complete the required fields in the Organization information and OAuth Domain & URIs section, then click Submit.
  3. Open the Secrets tab to find your Client ID and Client Secret.
  4. Use your integration’s authorization URL to set the required page permissions. Then send a request to obtain your Access Token. The official Notion documentation provides detailed instructions. You can proceed after getting your Client ID, Client Secret and Access Token.

Step 3: Set up the connector in Airbyte

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

Authentication for Airbyte Cloud

  • OAuth2.0 (Recommended): Click Authenticate your Notion account. In the popup, click Select pages. Select the pages you want Airbyte to access, then click Allow access.
  • Access Token: Copy the Access Token from the Secrets tab on your private integration’s page, then paste it.

Authentication for Airbyte Open Source

  • Access Token: Copy the Access Token from the Secrets tab on your private integration’s page, then paste it.
  • OAuth2.0: Copy and paste the Client ID, Client Secret and Access Token from your public integration setup.
  1. (Optional) Provide a Start Date using the datepicker or enter a UTC date and time in this format: YYYY-MM-DDTHH:mm:ss.SSSZ. Incremental syncs only replicate data generated after this date. If blank, the start date defaults to two years before the current date.
  2. Click Set up source and wait for the tests to finish.

Supported sync modes

The Notion source connector supports these sync modes:

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

Supported streams

The Notion source connector supports these streams:

  • Blocks: Retrieves content blocks from every synced page. This includes recursively nested child blocks up to 30 levels deep. It excludes block types child_page, child_database and ai_block.
  • Comments: Retrieves comments from every synced page. Requires the Read comments integration capability.
  • Data Sources: Retrieves data source objects. In the Notion API 2025-09-03, a data source is a structured table containing pages and properties. It was previously called a “database”. Since v4.0.0, this stream replaces the former Databases stream. For migration details, see the Notion migration guide.
  • Pages: Retrieves page objects from every shared page.
  • Users: Retrieves user objects from the workspace. Requires the Read user information integration capability.

Performance considerations

The Notion API limits each integration to approximately three requests per second. After an HTTP 429 response, the connector follows the Retry-After header and retries automatically. Rate-limited requests don’t count towards the maximum retry limit. Syncs continue indefinitely until the rate limit clears. For more information, see Notion’s request limits documentation.

The Blocks stream recursively fetches child blocks up to 30 levels deep. Deeply nested pages can generate many API requests. This may slow syncs for workspaces with complex page structures.

IP allow list

If Airbyte Cloud access is restricted to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
4.0.332026-11-1091664Update dependencies
4.0.322026-11-0390393Consolidate each stream’s error handling into a single error handler
4.0.312026-11-0390664Update dependencies
4.0.302026-10-2790033Update dependencies
4.0.292026-10-2089299Update dependencies
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-281082Roll 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-2778500Remove 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-2178343Revert 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-0672925Add 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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.