Skip to main content
POST
/
v1
/
data_sources
/
{data_source_id}
/
query
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.dataSources.query({
  data_source_id: "d9824bdc-8445-4327-be8b-5b47500af6ce",
  filter: {
    property: "Status",
    select: { equals: "Done" }
  },
  sorts: [
    {
      property: "Created",
      direction: "descending"
    }
  ]
})
{
  "type": "<string>",
  "page_or_data_source": {},
  "object": "<string>",
  "next_cursor": "<string>",
  "has_more": true,
  "results": [
    {
      "object": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_time": "2023-11-07T05:31:56Z",
      "last_edited_time": "2023-11-07T05:31:56Z",
      "in_trash": true,
      "is_archived": true,
      "is_locked": true,
      "url": "<string>",
      "public_url": "<string>",
      "parent": {
        "type": "<string>",
        "database_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "properties": {},
      "icon": {
        "type": "<string>",
        "emoji": "<string>"
      },
      "cover": {
        "type": "<string>",
        "file": {
          "url": "<string>",
          "expiry_time": "2023-11-07T05:31:56Z"
        }
      },
      "created_by": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "object": "<string>"
      },
      "last_edited_by": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "object": "<string>"
      }
    }
  ],
  "request_status": {}
}

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
  1. 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.
  2. 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[]
​
filter
object
​
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
​
request_status
object