> 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. # Retrieve a database GET https://api.notion.com/v1/databases/{database_id}/ 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: * [Retrieve a database](/reference/database-retrieve) * [Retrieve a data source](/reference/retrieve-a-data-source) Retrieves a [database object](https://developers.notion.com/reference/database) — information that describes the structure and columns of a database — for a provided database ID. The response adheres to any limits to an integration's capabilities. To fetch database rows rather than columns, use the [Query a database](https://developers.notion.com/reference/post-database-query) endpoint. To find a database ID, navigate to the database URL in your Notion workspace. The ID is the string of characters in the URL that is between the slash following the workspace name (if applicable) and the question mark. The ID is a 32 characters alphanumeric string. Refer to the [Build your first integration guide](https://developers.notion.com/docs/create-a-notion-integration#step-3-save-the-database-id) for more details. ### Errors 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. ### Additional resources * [How to share a database with your integration](https://developers.notion.com/docs/create-a-notion-integration#give-your-integration-page-permissions) * [Working with databases guide](https://developers.notion.com/docs/working-with-databases) To retrieve database properties from [database relations](https://www.notion.so/help/relations-and-rollups#what-is-a-database-relation), the related database must be shared with your integration in addition to the database being retrieved. If the related database is not shared, properties based on relations will not be included in the API response. To fetch the information in a [linked database](https://www.notion.so/help/guides/using-linked-databases), share the original source database with your Notion integration. Reference: https://notion.ferndocs.com/reference/retrieve-a-database ## Request ### Path parameters - `database_id` (string, required) — An identifier for the Notion database. ### Headers - `Notion-Version` (string, required) — The [API version](/reference/versioning) to use for this request. The latest version is `<>`. ## Response ### 200 200 - `object` (string, optional) - `id` (string, optional) - `created_time` (string, optional) - `last_edited_time` (string, optional) - `icon` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaIcon, optional) - `cover` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaCover, optional) - `url` (string, optional) - `title` (list of V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaTitleItems, optional) - `description` (list of V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionItems, optional) - `properties` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchema, optional) - `parent` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaParent, optional) - `archived` (boolean, optional, default: true) - `is_inline` (boolean, optional, default: true) - `public_url` (any, optional) ## Errors ### 400 Bad Request Error 400 ### 404 Not Found Error 404 - `object` (string, optional) - `status` (integer, optional, default: 0) - `code` (string, optional) - `message` (string, optional) ### 429 Too Many Requests Error 429 - `object` (string, optional) - `status` (integer, optional, default: 0) - `code` (string, optional) - `message` (string, optional) ## Types ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaIcon - `type` (string, optional) - `emoji` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaCover - `type` (string, optional) - `external` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaCoverExternal, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaTitleItems - `type` (string, optional) - `text` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaTitleItemsText, optional) - `annotations` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaTitleItemsAnnotations, optional) - `plain_text` (string, optional) - `href` (any, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionItems - `type` (string, optional) - `text` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionItemsText, optional) - `annotations` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionItemsAnnotations, optional) - `plain_text` (string, optional) - `href` (any, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchema - `+1` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchema1, optional) - `In stock` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaInStock, optional) - `Price` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPrice, optional) - `Description` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescription, optional) - `Last ordered` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaLastOrdered, optional) - `Meals` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaMeals, optional) - `Number of meals` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaNumberOfMeals, optional) - `Store availability` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaStoreAvailability, optional) - `Photo` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPhoto, optional) - `Food group` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaFoodGroup, optional) - `Name` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaName, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaParent - `type` (string, optional) - `page_id` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaCoverExternal - `url` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaTitleItemsText - `content` (string, optional) - `link` (any, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaTitleItemsAnnotations - `bold` (boolean, optional, default: true) - `italic` (boolean, optional, default: true) - `strikethrough` (boolean, optional, default: true) - `underline` (boolean, optional, default: true) - `code` (boolean, optional, default: true) - `color` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionItemsText - `content` (string, optional) - `link` (any, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionItemsAnnotations - `bold` (boolean, optional, default: true) - `italic` (boolean, optional, default: true) - `strikethrough` (boolean, optional, default: true) - `underline` (boolean, optional, default: true) - `code` (boolean, optional, default: true) - `color` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchema1 - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `people` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchema1People, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaInStock - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `checkbox` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaInStockCheckbox, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPrice - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `number` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPriceNumber, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescription - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `rich_text` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionRichText, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaLastOrdered - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `date` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaLastOrderedDate, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaMeals - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `relation` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaMealsRelation, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaNumberOfMeals - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `rollup` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaNumberOfMealsRollup, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaStoreAvailability - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `multi_select` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaStoreAvailabilityMultiSelect, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPhoto - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `files` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPhotoFiles, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaFoodGroup - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `select` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaFoodGroupSelect, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaName - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) - `title` (V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaNameTitle, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchema1People ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaInStockCheckbox ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPriceNumber - `format` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaDescriptionRichText ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaLastOrderedDate ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaMealsRelation - `database_id` (string, optional) - `synced_property_name` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaNumberOfMealsRollup - `rollup_property_name` (string, optional) - `relation_property_name` (string, optional) - `rollup_property_id` (string, optional) - `relation_property_id` (string, optional) - `function` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaStoreAvailabilityMultiSelect - `options` (list of V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaStoreAvailabilityMultiSelectOptionsItems, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaPhotoFiles ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaFoodGroupSelect - `options` (list of V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaFoodGroupSelectOptionsItems, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaNameTitle ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaStoreAvailabilityMultiSelectOptionsItems - `id` (string, optional) - `name` (string, optional) - `color` (string, optional) ### V1DatabasesDatabaseIdGetResponsesContentApplicationJsonSchemaFoodGroupSelectOptionsItems - `id` (string, optional) - `name` (string, optional) - `color` (string, optional) ## Examples **Response** ```json { "Result": { "value": "{\n \"object\": \"database\",\n \"id\": \"bc1211ca-e3f1-4939-ae34-5260b16f627c\",\n \"created_time\": \"2021-07-08T23:50:00.000Z\",\n \"last_edited_time\": \"2021-07-08T23:50:00.000Z\",\n \"icon\": {\n \"type\": \"emoji\",\n \"emoji\": \"🎉\"\n },\n \"cover\": {\n \"type\": \"external\",\n \"external\": {\n \"url\": \"https://website.domain/images/image.png\"\n }\n },\n \"url\": \"https://www.notion.so/bc1211cae3f14939ae34260b16f627c\",\n \"title\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"Grocery List\",\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\": \"Grocery List\",\n \"href\": null\n }\n ],\n \"description\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"content\": \"Grocery list for just 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\": \"Grocery list for just kale 🥬\",\n \"href\": null\n }\n ],\n \"properties\": {\n \"+1\": {\n \"id\": \"Wp%3DC\",\n \"name\": \"+1\",\n \"type\": \"people\",\n \"people\": {}\n },\n \"In stock\": {\n \"id\": \"fk%5EY\",\n \"name\": \"In stock\",\n \"type\": \"checkbox\",\n \"checkbox\": {}\n },\n \"Price\": {\n \"id\": \"evWq\",\n \"name\": \"Price\",\n \"type\": \"number\",\n \"number\": {\n \"format\": \"dollar\"\n }\n },\n \"Description\": {\n \"id\": \"V}lX\",\n \"name\": \"Description\",\n \"type\": \"rich_text\",\n \"rich_text\": {}\n },\n \"Last ordered\": {\n \"id\": \"eVnV\",\n \"name\": \"Last ordered\",\n \"type\": \"date\",\n \"date\": {}\n },\n \"Meals\": {\n \"id\": \"%7DWA~\",\n \"name\": \"Meals\",\n \"type\": \"relation\",\n \"relation\": {\n \"database_id\": \"668d797c-76fa-4934-9b05-ad288df2d136\",\n \"synced_property_name\": \"Related to Grocery List (Meals)\"\n }\n },\n \"Number of meals\": {\n \"id\": \"Z\\\\Eh\",\n \"name\": \"Number of meals\",\n \"type\": \"rollup\",\n \"rollup\": {\n \"rollup_property_name\": \"Name\",\n \"relation_property_name\": \"Meals\",\n \"rollup_property_id\": \"title\",\n \"relation_property_id\": \"mxp^\",\n \"function\": \"count\"\n }\n },\n \"Store availability\": {\n \"id\": \"s}Kq\",\n \"name\": \"Store availability\",\n \"type\": \"multi_select\",\n \"multi_select\": {\n \"options\": [\n {\n \"id\": \"cb79b393-d1c1-4528-b517-c450859de766\",\n \"name\": \"Duc Loi Market\",\n \"color\": \"blue\"\n },\n {\n \"id\": \"58aae162-75d4-403b-a793-3bc7308e4cd2\",\n \"name\": \"Rainbow Grocery\",\n \"color\": \"gray\"\n },\n {\n \"id\": \"22d0f199-babc-44ff-bd80-a9eae3e3fcbf\",\n \"name\": \"Nijiya Market\",\n \"color\": \"purple\"\n },\n {\n \"id\": \"0d069987-ffb0-4347-bde2-8e4068003dbc\",\n \"name\": \"Gus's Community Market\",\n \"color\": \"yellow\"\n }\n ]\n }\n },\n \"Photo\": {\n \"id\": \"yfiK\",\n \"name\": \"Photo\",\n \"type\": \"files\",\n \"files\": {}\n },\n \"Food group\": {\n \"id\": \"CM%3EH\",\n \"name\": \"Food group\",\n \"type\": \"select\",\n \"select\": {\n \"options\": [\n {\n \"id\": \"6d4523fa-88cb-4ffd-9364-1e39d0f4e566\",\n \"name\": \"🥦Vegetable\",\n \"color\": \"green\"\n },\n {\n \"id\": \"268d7e75-de8f-4c4b-8b9d-de0f97021833\",\n \"name\": \"🍎Fruit\",\n \"color\": \"red\"\n },\n {\n \"id\": \"1b234a00-dc97-489c-b987-829264cfdfef\",\n \"name\": \"💪Protein\",\n \"color\": \"yellow\"\n }\n ]\n }\n },\n \"Name\": {\n \"id\": \"title\",\n \"name\": \"Name\",\n \"type\": \"title\",\n \"title\": {}\n }\n },\n \"parent\": {\n \"type\": \"page_id\",\n \"page_id\": \"98ad959b-2b6a-4774-80ee-00246fb0ea9b\"\n },\n \"archived\": false,\n \"is_inline\": false,\n \"public_url\": null\n}" } } ``` **SDK Code** ```javascript Notion SDK for JavaScript const { Client } = require('@notionhq/client'); const notion = new Client({ auth: process.env.NOTION_API_KEY }); (async () => { const databaseId = '668d797c-76fa-4934-9b05-ad288df2d136'; const response = await notion.databases.retrieve({ database_id: databaseId }); console.log(response); })(); ``` ```python import requests url = "https://api.notion.com/v1/databases/database_id/" headers = {"Notion-Version": "Notion-Version"} response = requests.get(url, headers=headers) print(response.json()) ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.notion.com/v1/databases/database_id/" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Notion-Version", "Notion-Version") 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/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Notion-Version"] = 'Notion-Version' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.notion.com/v1/databases/database_id/") .header("Notion-Version", "Notion-Version") .asString(); ``` ```php request('GET', 'https://api.notion.com/v1/databases/database_id/', [ 'headers' => [ 'Notion-Version' => 'Notion-Version', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.notion.com/v1/databases/database_id/"); var request = new RestRequest(Method.GET); request.AddHeader("Notion-Version", "Notion-Version"); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Notion-Version": "Notion-Version"] let request = NSMutableURLRequest(url: NSURL(string: "https://api.notion.com/v1/databases/database_id/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers 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() ```