> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://notion.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server. # Query a database POST https://api.notion.com/v1/databases/{database_id}/query Content-Type: application/json This page describes the API for versions up to and including `2022-06-28`. In the new `2025-09-03` version, the concepts of databases and data sources were split up, as described in [Upgrading to 2025-09-03](/docs/upgrade-guide-2025-09-03). Refer to the new APIs instead: * [Query a data source](/reference/query-a-data-source) Gets a list of [Pages](/reference/page) and/or [Databases](https://developers.notion.com/reference/database) 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](https://developers.notion.com/reference/intro#pagination) for details about how to use a cursor to iterate through the list. [Wiki](https://www.notion.so/help/wikis-and-verified-pages) databases can contain both pages and databases as children. [**Filters**](/reference/post-database-query-filter) are similar to the [filters provided in the Notion UI](https://www.notion.so/help/views-filters-and-sorts) 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. ```json 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. ```json JSON { "property": "Done", "checkbox": { "equals": true } } ``` [**Sorts**](/reference/post-database-query-sort) are similar to the [sorts provided in the Notion UI](https://notion.so/notion/Intro-to-databases-fd8cd2d212f74c50954c11086d85997e#0eb303043b1742468e5aff2f3f670505). 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](https://developers.notion.com/reference/retrieve-a-database) endpoint. If you are using the [Notion JavaScript SDK](https://github.com/makenotion/notion-sdk-js), the `filter_properties` endpoint expects an array of property ID strings. ```JavaScript JavaScript notion.databases.query({ database_id: id, filter_properties: ["propertyID1", "propertyID2"] }) ``` 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. 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](/reference/capabilities). 1. 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. 2. Otherwise, [retrieve the individual related pages](https://developers.notion.com/reference/retrieve-a-page) using each page ID. * 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. ### 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](/reference/request-limits). *Note: Each Public API endpoint can return several possible error codes. See the [Error codes section](https://developers.notion.com/reference/status-codes#error-codes) of the Status codes documentation for more information.* Reference: https://notion.ferndocs.com/reference/post-database-query ## Request ### Path parameters - `database_id` (string, required) — Identifier for a Notion database. ### Query parameters - `filter_properties` (string, optional) — A list of page property value IDs associated with the database. Use this param to limit the response to a specific page property value or values for pages that meet the `filter` criteria. ### Headers - `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<>`. ### Body (application/json) This endpoint expects an object. - `filter` (string, optional) — When supplied, limits which pages are returned based on the [filter conditions](ref:post-database-query-filter). - `sorts` (list of any, optional) — When supplied, orders the results based on the provided [sort criteria](ref:post-database-query-sort). - `start_cursor` (string, optional) — When supplied, returns a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results. - `page_size` (integer, optional, default: 100) — The number of items from the full list desired in the response. Maximum: 100 ## Response ### 200 200 - `object` (string, optional) - `results` (list of V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItems, optional) - `next_cursor` (any, optional) - `has_more` (boolean, optional, default: true) - `type` (string, optional) - `page_or_database` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaPageOrDatabase, optional) ## Errors ### 400 Bad Request Error 400 ## Types ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItems - `object` (string, optional) - `id` (string, optional) - `created_time` (string, optional) - `last_edited_time` (string, optional) - `created_by` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsCreatedBy, optional) - `last_edited_by` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsLastEditedBy, optional) - `cover` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsCover, optional) - `icon` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsIcon, optional) - `parent` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsParent, optional) - `archived` (boolean, optional, default: true) - `properties` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItems, optional) - `url` (string, optional) ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaPageOrDatabase ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsCreatedBy - `object` (string, optional) - `id` (string, optional) ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsLastEditedBy - `object` (string, optional) - `id` (string, optional) ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsCover - `type` (string, optional) - `external` (V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsCoverExternal, optional) ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsIcon - `type` (string, optional) - `emoji` (string, optional) ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsParent - `type` (string, optional) - `database_id` (string, optional) ### V1DatabasesDatabaseIdQueryPostResponsesContentApplicationJsonSchemaResultsItemsCoverExternal - `url` (string, optional) ## Examples **Request** ```json {} ``` **Response** ```json { "Result": { "value": "{\n \"object\": \"list\",\n \"results\": [\n {\n \"object\": \"page\",\n \"id\": \"59833787-2cf9-4fdf-8782-e53db20768a5\",\n \"created_time\": \"2022-03-01T19:05:00.000Z\",\n \"last_edited_time\": \"2022-07-06T20:25:00.000Z\",\n \"created_by\": {\n \"object\": \"user\",\n \"id\": \"ee5f0f84-409a-440f-983a-a5315961c6e4\"\n },\n \"last_edited_by\": {\n \"object\": \"user\",\n \"id\": \"0c3e9826-b8f7-4f73-927d-2caaf86f1103\"\n },\n \"cover\": {\n \"type\": \"external\",\n \"external\": {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg\"\n }\n },\n \"icon\": {\n \"type\": \"emoji\",\n \"emoji\": \"🥬\"\n },\n \"parent\": {\n \"type\": \"database_id\",\n \"database_id\": \"d9824bdc-8445-4327-be8b-5b47500af6ce\"\n },\n \"archived\": false,\n \"properties\": {\n \"Store availability\": {\n \"id\": \"%3AUPp\",\n \"type\": \"multi_select\",\n \"multi_select\": [\n {\n \"id\": \"t|O@\",\n \"name\": \"Gus's Community Market\",\n \"color\": \"yellow\"\n },\n {\n \"id\": \"{Ml\\\\\",\n \"name\": \"Rainbow Grocery\",\n \"color\": \"gray\"\n }\n ]\n },\n \"Food group\": {\n \"id\": \"A%40Hk\",\n \"type\": \"select\",\n \"select\": {\n \"id\": \"5e8e7e8f-432e-4d8a-8166-1821e10225fc\",\n \"name\": \"🥬 Vegetable\",\n \"color\": \"pink\"\n }\n },\n \"Price\": {\n \"id\": \"BJXS\",\n \"type\": \"number\",\n \"number\": 2.5\n },\n \"Responsible Person\": {\n \"id\": \"Iowm\",\n \"type\": \"people\",\n \"people\": [\n {\n \"object\": \"user\",\n \"id\": \"cbfe3c6e-71cf-4cd3-b6e7-02f38f371bcc\",\n \"name\": \"Cristina Cordova\",\n \"avatar_url\": \"https://lh6.googleusercontent.com/-rapvfCoTq5A/AAAAAAAAAAI/AAAAAAAAAAA/AKF05nDKmmUpkpFvWNBzvu9rnZEy7cbl8Q/photo.jpg\",\n \"type\": \"person\",\n \"person\": {\n \"email\": \"cristina@makenotion.com\"\n }\n }\n ]\n },\n \"Last ordered\": {\n \"id\": \"Jsfb\",\n \"type\": \"date\",\n \"date\": {\n \"start\": \"2022-02-22\",\n \"end\": null,\n \"time_zone\": null\n }\n },\n \"Cost of next trip\": {\n \"id\": \"WOd%3B\",\n \"type\": \"formula\",\n \"formula\": {\n \"type\": \"number\",\n \"number\": 0\n }\n },\n \"Recipes\": {\n \"id\": \"YfIu\",\n \"type\": \"relation\",\n \"relation\": [\n {\n \"id\": \"90eeeed8-2cdd-4af4-9cc1-3d24aff5f63c\"\n },\n {\n \"id\": \"a2da43ee-d43c-4285-8ae2-6d811f12629a\"\n }\n ],\n\t\t\t\t\t\"has_more\": false\n },\n \"Description\": {\n \"id\": \"_Tc_\",\n \"type\": \"rich_text\",\n \"rich_text\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"A dark \",\n \"link\": null\n },\n \"annotations\": {\n \"bold\": false,\n \"italic\": false,\n \"strikethrough\": false,\n \"underline\": false,\n \"code\": false,\n \"color\": \"default\"\n },\n \"plain_text\": \"A dark \",\n \"href\": null\n },\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"green\",\n \"link\": null\n },\n \"annotations\": {\n \"bold\": false,\n \"italic\": false,\n \"strikethrough\": false,\n \"underline\": false,\n \"code\": false,\n \"color\": \"green\"\n },\n \"plain_text\": \"green\",\n \"href\": null\n },\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \" leafy vegetable\",\n \"link\": null\n },\n \"annotations\": {\n \"bold\": false,\n \"italic\": false,\n \"strikethrough\": false,\n \"underline\": false,\n \"code\": false,\n \"color\": \"default\"\n },\n \"plain_text\": \" leafy vegetable\",\n \"href\": null\n }\n ]\n },\n \"In stock\": {\n \"id\": \"%60%5Bq%3F\",\n \"type\": \"checkbox\",\n \"checkbox\": true\n },\n \"Number of meals\": {\n \"id\": \"zag~\",\n \"type\": \"rollup\",\n \"rollup\": {\n \"type\": \"number\",\n \"number\": 2,\n \"function\": \"count\"\n }\n },\n \"Photo\": {\n \"id\": \"%7DF_L\",\n \"type\": \"url\",\n \"url\": \"https://i.insider.com/612fb23c9ef1e50018f93198?width=1136&format=jpeg\"\n },\n \"Name\": {\n \"id\": \"title\",\n \"type\": \"title\",\n \"title\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"Tuscan kale\",\n \"link\": null\n },\n \"annotations\": {\n \"bold\": false,\n \"italic\": false,\n \"strikethrough\": false,\n \"underline\": false,\n \"code\": false,\n \"color\": \"default\"\n },\n \"plain_text\": \"Tuscan kale\",\n \"href\": null\n }\n ]\n }\n },\n \"url\": \"https://www.notion.so/Tuscan-kale-598337872cf94fdf8782e53db20768a5\"\n }\n ],\n \"next_cursor\": null,\n \"has_more\": false,\n \"type\": \"page_or_database\",\n\t\"page_or_database\": {}\n}" } } ``` **SDK Code** ```javascript const { Client } = require('@notionhq/client'); const notion = new Client({ auth: process.env.NOTION_API_KEY }); (async () => { const databaseId = 'd9824bdc-8445-4327-be8b-5b47500af6ce'; const response = await notion.databases.query({ database_id: databaseId, filter: { or: [ { property: 'In stock', checkbox: { equals: true, }, }, { property: 'Cost of next trip', number: { greater_than_or_equal_to: 2, }, }, ], }, sorts: [ { property: 'Last ordered', direction: 'ascending', }, ], }); console.log(response); })(); ``` ```python import requests url = "https://api.notion.com/v1/databases/database_id/query" payload = {} headers = { "Notion-Version": "Notion-Version", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.notion.com/v1/databases/database_id/query" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Notion-Version", "Notion-Version") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.notion.com/v1/databases/database_id/query") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Notion-Version"] = 'Notion-Version' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.notion.com/v1/databases/database_id/query") .header("Notion-Version", "Notion-Version") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('POST', 'https://api.notion.com/v1/databases/database_id/query', [ 'body' => '{}', 'headers' => [ 'Content-Type' => 'application/json', 'Notion-Version' => 'Notion-Version', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.notion.com/v1/databases/database_id/query"); var request = new RestRequest(Method.POST); request.AddHeader("Notion-Version", "Notion-Version"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Notion-Version": "Notion-Version", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/databases/database_id/query")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```