Skip to main content

​
Overview

Retrieves a database object by its ID. Returns information about the database including its title, description, parent, data sources, and metadata. 
const database = await notion.databases.retrieve({
  database_id: '897e5a76-ae52-4b48-a6d4-0b46543ebcda'
})

console.log(database.title)
console.log(database.data_sources)

​
Parameters

​
database_id
string
required
The ID of the database to retrieve. Can be a raw ID or a Notion database URL.
​
auth
string
Optional authentication token to override the client’s default token for this request.

​
Response

Returns a DatabaseObjectResponse or PartialDatabaseObjectResponse.
​
object
string
Always database.
​
id
string
The ID of the database.
​
title
array
The title of the database as an array of rich text objects.
​
description
array
The description of the database as an array of rich text objects.
​
parent
object
The parent of the database. Can be a page, block, workspace, or another database.
​
is_inline
boolean
Whether the database is displayed inline in the parent page.
​
in_trash
boolean
Whether the database is in the trash.
​
is_locked
boolean
Whether the database is locked from editing in the Notion app UI.
​
created_time
string
ISO 8601 timestamp when the database was created.
​
last_edited_time
string
ISO 8601 timestamp when the database was last edited.
​
data_sources
array
Array of data source references contained in this database. Each reference includes an ID and name.
​
icon
object
The icon of the database, or null if none is set.
​
cover
object
The cover image of the database, or null if none is set.
​
url
string
The URL of the database in Notion.
​
public_url
string
The public URL of the database if it is publicly accessible, otherwise null.

​
Examples

​
Retrieve a database

const database = await notion.databases.retrieve({
  database_id: '897e5a76-ae52-4b48-a6d4-0b46543ebcda'
})

console.log('Database:', database.title[0].plain_text)
console.log('Data sources:', database.data_sources.length)
console.log('Created:', database.created_time)

​
Retrieve and check database properties

const database = await notion.databases.retrieve({
  database_id: '897e5a76-ae52-4b48'
})

if (database.is_inline) {
  console.log('This is an inline database')
}

if (database.in_trash) {
  console.log('This database is in the trash')
}

if (database.is_locked) {
  console.log('This database is locked')
}

​
Extract database ID from URL

const { extractDatabaseId } = require('@notionhq/client')

const url = 'https://www.notion.so/myworkspace/897e5a76ae524b48a6d40b46543ebcda'
const databaseId = extractDatabaseId(url)

const database = await notion.databases.retrieve({
  database_id: databaseId
})

console.log(database.title)

​
Access data sources

const database = await notion.databases.retrieve({
  database_id: 'database-id'
})

for (const dataSource of database.data_sources) {
  console.log(`Data source: ${dataSource.name} (${dataSource.id})`)
  
  const results = await notion.dataSources.query({
    data_source_id: dataSource.id
  })
  
  console.log(`  Pages: ${results.results.length}`)
}
To query the contents of a database, use notion.dataSources.query() with one of the data source IDs from the data_sources array.

Build docs developers (and LLMs) love

Get started for freeTalk to us