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.

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 integration 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 an integration can query a data source, its parent database must be shared with the integration. Attempting to query a database that has not been shared will return an HTTP response with a 404 status code.To share a database with an integration, 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 integration from the dropdown list.

Integration capabilitiesThis endpoint requires an integration 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 integration 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 integration doesn’t have access to the data source. Returns a 400 or a 429 HTTP response if the request exceeds the request limits.

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 2025-09-03.

Available options:

2025-09-03

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<uuid>

page_size

number

archived

boolean

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

object

any

required

message

string

required

code

enum<string>

required

Available options:

invalid_json,

invalid_request_url,

invalid_request,

missing_version,

validation_error

status

any

required

additional_data

object

Show child attributes

Notion API

Objects

Endpoints

Overview

Filtering

Sorting

Recommendations for performance

Other important details and tips

Errors

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Notion API

Objects

Endpoints

​Overview

​Filtering

​Sorting

​Recommendations for performance

​Other important details and tips

​Errors

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Overview

Filtering

Sorting

Recommendations for performance

Other important details and tips

Errors