Query a data source
Query a data source
POST
TypeScript SDK
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 thanpage_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
Use filters to match property values. Combine conditions withand or or. This filter returns rows where Done is checked and Tags contains A or B.

The above filters in the UI can be represented as the following filter object
Filter object
JSON
Archived pages
Page objects useis_archived to indicate whether a page is archived.
Use the top-level archive_status body parameter to select active pages, archived pages, or both.
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 stops at the 10,000th result:has_more becomes false, and every response page served from the capped result includes a request_status marking the result as incomplete:
request_status.type === "incomplete" on every response page to know whether a query was cut off. Any page with that status means the whole query result was capped. The limit is per query (a query is defined by its filter and sort), not per data source.
For connections that need to process all pages in a large data source, we recommend:
- Reading every row past the limit by partitioning the query into
created_timewindows. See Query large data sources for the technique and a runnable cookbook example. - Using filters to narrow the result set (e.g. filter by
last_edited_timeto fetch only recently changed pages). - Setting up connection webhooks for incremental sync instead of polling the full data source on a schedule.
Recommendations for performance
Passfilter_properties once per property in the query string, or pass an array of strings in the SDK. Use property names or IDs from Retrieve a data source. For example, for a data source with a Status property:
filter_properties can speed up the query and reduce its response size, especially for data sources with many properties, formulas, rollups, or relations. Use this endpoint to find pages and return only the properties your list shows. Fetch more data after you select a page:
- Call Retrieve a page with the returned page ID to get more properties from one page. You can also pass
filter_propertiesto that endpoint. - Call Retrieve a page property with the page and property IDs to retrieve one property. Use it when a formula, rollup, or relation contains more than 25 references.
- 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.
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.
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 anadditional_data object with retry guidance:
503 response example
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
Headers
The API version to use for this request. The latest version is 2026-03-11.
Available options:
2026-03-11 Query Parameters
Body
application/json
A property filter, timestamp filter, or compound and/or filter.
- Option 1
- Option 2
- Title
- Rich Text
- Number
- Checkbox
- Select
- Multi Select
- Status
- Date
- People
- Files
- Url
- Email
- Phone Number
- Relation
- Created By
- Created Time
- Last Edited By
- Last Edited Time
- Formula
- Unique Id
- Rollup
- Verification
- Created Time
- Last Edited Time