Query a data source

Overview

Gets a list of pages contained in the data source, filtered and ordered according to the filter conditions and sort criteria provided in the request. The response may contain fewer than page_size of results. If the response includes a next_cursor value, refer to the pagination reference for details about how to use a cursor to iterate through the list.

Databases, data sources, and wikisWiki data sources can contain either pages or databases as children. In all other cases, the children can only be pages.For wikis, instead of directly returning any database results, this API returns all data sources that are children of that database. Surfacing the data source instead of the direct database child helps make it easier to craft your next API request (for example, retrieving the data source or listing its children.)Another tip for wikis is to use the result_type filter of "page" or "data_source" if you’re only looking for query results that are one of those two types instead of both.

Filtering

Filters are similar to the filters provided in the Notion UI where the set of filters and filter groups chained by “And” in the UI is equivalent to having each filter in the array of the compound "and" filter. Similar a set of filters chained by “Or” in the UI would be represented as filters in the array of the "or" compound filter. Filters operate on data source properties and can be combined. If no filter is provided, all the pages in the data source will be returned with pagination.

Filter object

{
  "and": [
    {
      "property": "Done",
      "checkbox": {
        "equals": true
      }
    },
    {
      "or": [
        {
          "property": "Tags",
          "contains": "A"
        },
        {
          "property": "Tags",
          "contains": "B"
        }
      ]
  	}
  ]
}

In addition to chained filters, data sources can be queried with single filters.

JSON

{
    "property": "Done",
    "checkbox": {
        "equals": true
   }
 }

Sorting

Sorts are similar to the sorts provided in the Notion UI. Sorts operate on database properties or page timestamps and can be combined. The order of the sorts in the request matter, with earlier sorts taking precedence over later ones. Notion doesn’t guarantee any particular sort order when no sort parameters are provided.

Pagination limit

This endpoint supports paginating through up to 10,000 results per query. If a data source contains more matching entries than this limit, pagination will stop at the 10,000th result. For connections that need to process all pages in a large data source, we recommend:

Using filters to narrow the result set (e.g. filter by last_edited_time to fetch only recently changed pages).
Setting up connection webhooks for incremental sync instead of polling the full data source on a schedule.

Incremental sync via webhooksIf your connection polls this endpoint on a recurring schedule to detect changes, consider switching to connection webhooks instead. Webhooks notify your connection of changes in real time, eliminating the need to paginate through the entire data source. This is faster, more efficient, and avoids hitting the pagination limit.

Recommendations for performance

Use the filter_properties query parameter to filter only the properties of the data source schema you need from the response items. For example:

https://api.notion.com/v1/data_sources/[DATA_SOURCE_ID]/query?filter_properties[]=title

Multiple filter properties can be provided by chaining the filter_properties query param. For example:

https://api.notion.com/v1/data_sources/[DATA_SOURCE_ID]/query?filter_properties[]=title&filter_properties[]=status

This parameter accepts property IDs or property names. Property IDs can be determined with the Retrieve a data source endpoint. If you are using the Notion JavaScript SDK, the filter_properties endpoint expects an array of strings. For example:

TypeScript

notion.dataSources.query({
	data_source_id: id,
	filter_properties: ["title", "status"]
})

Using filter_properties can make a significant improvement to the speed of the API and size of the JSON objects in the results, especially for databases with lots of properties, some of which might be rollups, relations, or formulas. If you need additional properties from each returned page, you can make subsequent calls to the Retrieve page property item or Retrieve a page APIs. If you’re still running into long query times with this API, other tips include:

Using more specific filter conditions to reduce the result set, e.g. a more specific title query or a shorter time window.
Dividing large data sources (ones with more than several dozen thousand pages) into multiple; e.g. splitting a “tasks” database into “Tasks” and “Bugs”.
Pruning data source schemas to remove any complex formulas, rollups, two-way relations, or other properties that are no longer in use.
Setting up connection webhooks to reduce the need for polling this API by instead automatically notifying your system of incremental workspace events.

For more information, visit our help center article on optimizing database load times.

Other important details and tips

PermissionsBefore a connection can query a data source, its parent database must be shared with the connection. Attempting to query a data source in a database that has not been shared will return an HTTP response with a 404 status code.To share a database with a connection, click the ••• menu at the top right of a database page, scroll to Add connections, and use the search bar to find and select the connection from the dropdown list.

Connection capabilitiesThis endpoint requires a connection to have read content capabilities. Attempting to call this API without read content capabilities will return an HTTP response with a 403 status code. For more information on connection capabilities, see the capabilities guide.

To display the page titles of related pages rather than just the ID:

Add a rollup property to the data source which uses a formula to get the related page’s title. This works well if you have access to update the data source’s schema.
Otherwise, retrieve the individual related pages using each page ID.

Formula and rollup limitations

If a formula depends on a page property that is a relation, and that relation has more than 25 references, only 25 will be evaluated as part of the formula.
Rollups and formulas that depend on multiple layers of relations may not return correct results.
Notion recommends individually retrieving each page property item to get the most accurate result.

Errors

Returns a 404 HTTP response if the data source doesn’t exist, or if the connection doesn’t have access to the data source. Returns a 400 or a 429 HTTP response if the request exceeds the request limits. Returns a 503 HTTP response if the data source query is temporarily unavailable due to backend datastore timeouts. The response body includes an additional_data object with retry guidance:

503 response example

{
  "object": "error",
  "status": 503,
  "code": "service_unavailable",
  "message": "Public API data source query is temporarily unavailable due to backend datastore timeouts. Retry with exponential backoff; if retries continue to fail, reduce page_size or narrow filters/sorts.",
  "additional_data": {
    "endpoint_name": "public_queryDataSource",
    "notion_error_name": "PgPoolWaitConnectionTimeout",
    "retry_guidance": [
      "Use exponential backoff with jitter",
      "Reduce page_size",
      "Narrow query filters/sorts"
    ]
  }
}

Note: Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version

enum<string>

required

The API version to use for this request. The latest version is 2026-03-11.

Available options:

2026-03-11

Path Parameters

data_source_id

string

required

Query Parameters

filter_properties

string[]

Body

application/json

sorts

object[]

Option 1
Option 2

Show child attributes

filter

object

Show child attributes

start_cursor

string

page_size

number

in_trash

boolean

result_type

enum<string>

Optionally filter the results to only include pages or data sources. Regular, non-wiki databases only support page children. The default behavior is no result type filtering, in other words, returning both pages and data sources for wikis.

Available options:

page,

data_source

Response

type

string

required

Allowed value: "page_or_data_source"

page_or_data_source

object

required

object

string

required

Allowed value: "list"

next_cursor

string | null

required

has_more

boolean

required

results

object[]

required

Option 1
Option 2
Option 3
Option 4

Show child attributes

request_status

object

Show child attributes

Notion API

Objects

Endpoints

Webhook events

Overview

Filtering

Sorting

Recommendations for performance

Other important details and tips

Errors

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Notion API

Objects

Endpoints

Webhook events

Documentation Index

​Overview

​Filtering

​Sorting

​Pagination limit

​Recommendations for performance

​Other important details and tips

​Errors

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Overview

Filtering

Sorting

Pagination limit

Recommendations for performance

Other important details and tips

Errors