Gets a list of Pages and/or Databases contained in the database, 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.
Wiki databases can contain both pages and databases as children.
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 database properties and can be combined. If no filter is provided, all the pages in the database will be returned with pagination.
The above filters in the UI can be represented as the following filter object
{
"and": [
{
"property": "Done",
"checkbox": {
"equals": true
}
},
{
"or": [
{
"property": "Tags",
"contains": "A"
},
{
"property": "Tags",
"contains": "B"
}
]
}
]
}
In addition to chained filters, databases can be queried with single filters.
{
"property": "Done",
"checkbox": {
"equals": true
}
}
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.
The properties of the database schema returned in the response body can be filtered with the filter_properties query parameter.
https://api.notion.com/v1/databases/[database_id]/query?filter_properties=[property_id_1]
Multiple filter properties can be provided by chaining the filter_properties query param.
https://api.notion.com/v1/databases/[database_id]/query?filter_properties=[property_id_1]&filter_properties=[property_id_2]
Property IDs can be determined with the Retrieve a database endpoint.
If you are using the Notion JavaScript SDK, the filter_properties endpoint expects an array of property ID strings.
notion.databases.query({
database_id: id,
filter_properties: ["propertyID1", "propertyID2"]
})
Permissions
Before an integration can query a database, the 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 capabilities
This 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 database which uses a formula to get the related page's title. This works well if you have access to updating the database's schema.
Otherwise, retrieve the individual related pages using each page ID.
Formula Limitation
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.
Errors
Returns a 404 HTTP response if the database doesn't exist, or if the integration doesn't have access to the database.
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.