databases.retrieve

Retrieve a database object by its ID

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.