Skip to main content
Data sources are the individual tables of data that live under a Notion database. Pages are the items (or children) in a data source. Page property values must conform to the property objects laid out in the parent data source object.
One database contains two data sources. Each data source has its own rows, shown as pages.

Database structure since API version 2025-09-03

As of API version 2025-09-03, there’s a suite of APIs for managing data sources:

Object fields

Properties marked with an asterisk (*) are available to connections with any capabilities. Other properties require read content capabilities in order to be returned from the Notion API. For more information on connection capabilities, see the capabilities guide.

Sync metadata

The optional, read-only sync_metadata field describes sync identity and available health. It is returned when retrieving or listing a readable synced data source. Retrieve a database also includes it on each readable entry in data_sources. Search, create, and update responses do not include it. The field requires read access to the data source and a read capability on the connection. It is omitted from partial responses and when stored metadata is unavailable or invalid. Its absence does not prove that the data source is not synced. For supported External Database Sync providers, these reads also query the sync service for current collection health. They do not start a sync or query the provider. If health is unavailable, health is null and the data source still returns successfully. The object has one of these stored representations: Sync IDs and collection keys are identifiers, not credentials, and do not grant access to manage a sync. This field does not include credentials, raw provider error messages, or sync configuration. Health errors contain a code and severity. For example, an external database sync returns:
owner_user_id identifies the Notion user who owns the sync credential. resource identifies the provider resource for this data source. Both are returned only when available from the health lookup. A paused sync without resource health returns health: { "paused": true } and omits resource. health.stage is initializing, backfilling, or steady. When ok is false, error contains a code and a severity of action_required, degraded, or failing. The checks timestamps are UTC ISO 8601 strings. Missing execution and checkpoint timestamps mean unknown; sync_version_updated_at records configuration changes, not successful ingestion. A null health value does not establish whether the sync is healthy or current.

Legacy sync state

sync_state is optional and applies only to legacy synced data sources. When present, it contains a required syncing field and may contain the timestamps below. All timestamps are UTC ISO 8601 strings. Missing timestamps and timestamps that cannot be represented are omitted rather than returned as null.
Schema limitationsNotion recommends a max property count of 500 or a max schema size of 50KB. Updates to database schemas that are too large will be blocked to help maintain database performance.