> ## 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.
# Retrieve a database
Retrieves a [database object](/reference/database) — a container for one or more [data sources](/reference/data-source) — for a provided database ID. The response adheres to any limits to a connection’s capabilities.
The most important fields in the database object response to highlight:
* `data_sources`: An array of JSON objects with the `id` and `name` of every data source under the database
* These data source IDs can be used with the [Retrieve a data source](/reference/retrieve-a-data-source), [Update a data source](/reference/update-a-data-source), and [Query a data source](/reference/query-a-data-source) APIs
* `parent`: The direct parent of the database; generally a `page_id` or `workspace: true`
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 connection guide](/guides/get-started/quick-start) for more details.
### Errors
Each Public API endpoint can return several possible error codes. See the [Error codes section](/reference/status-codes#error-codes) of the Status codes documentation for more information.
### Additional resources
* [How to share a database with your connection](/guides/get-started/quick-start#give-your-connection-page-permissions)
* [Working with databases guide](/guides/data-apis/working-with-databases)
## OpenAPI
````yaml get /v1/databases/{database_id}
openapi: 3.1.0
info:
title: Notion API
version: 1.0.0
termsOfService: >-
https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac
servers:
- url: https://api.notion.com
security:
- bearerAuth: []
tags:
- name: Databases
description: Database endpoints
- name: Data sources
description: Data source endpoints
- name: Pages
description: Page endpoints
- name: Blocks
description: Block endpoints
- name: Comments
description: Comment endpoints
- name: File uploads
description: File upload endpoints
- name: OAuth
description: OAuth endpoints (basic authentication)
- name: Users
description: User endpoints
- name: Search
description: Search endpoints
- name: Views
description: View endpoints
- name: Custom emojis
description: Custom emoji endpoints
- name: Meeting notes
description: Meeting notes endpoints
paths:
/v1/databases/{database_id}:
get:
tags:
- Databases
summary: Retrieve a database
operationId: retrieve-database
parameters:
- name: database_id
in: path
required: true
schema:
$ref: '#/components/schemas/idRequest'
description: ID of a Notion database, a container for one or more data sources.
- $ref: '#/components/parameters/notionVersion'
responses:
'200':
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/partialDatabaseObjectResponse'
- $ref: '#/components/schemas/databaseObjectResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_400'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_401'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_403'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_404'
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_409'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_429'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_500'
'503':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_503'
'504':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_api_504'
x-codeSamples:
- lang: javascript
label: TypeScript SDK
source: |-
import { Client } from "@notionhq/client"
const notion = new Client({ auth: process.env.NOTION_API_KEY })
const response = await notion.databases.retrieve({
database_id: "d9824bdc-8445-4327-be8b-5b47500af6ce"
})
components:
schemas:
idRequest:
type: string
partialDatabaseObjectResponse:
type: object
properties:
object:
type: string
const: database
description: The database object type name.
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the database.
additionalProperties: false
required:
- object
- id
databaseObjectResponse:
type: object
properties:
object:
type: string
const: database
description: The database object type name.
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the database.
title:
type: array
items:
$ref: '#/components/schemas/richTextItemResponse'
maxItems: 100
description: The title of the database.
description:
type: array
items:
$ref: '#/components/schemas/richTextItemResponse'
maxItems: 100
description: The description of the database.
parent:
$ref: '#/components/schemas/parentOfDatabaseResponse'
description: >-
The parent of the database. This is typically a page, block, or
workspace, but can be another database in the case of wikis.
is_inline:
type: boolean
description: Whether the database is inline.
in_trash:
type: boolean
description: Whether the database is in the trash.
is_locked:
type: boolean
description: Whether the database is locked from editing in the Notion app UI.
created_time:
type: string
format: date-time
description: The time when the database was created.
last_edited_time:
type: string
format: date-time
description: The time when the database was last edited.
data_sources:
type: array
items:
$ref: '#/components/schemas/dataSourceReferenceResponse'
maxItems: 100
description: The data sources of the database.
icon:
oneOf:
- $ref: '#/components/schemas/pageIconResponse'
- type: 'null'
description: The icon of the database.
cover:
oneOf:
- $ref: '#/components/schemas/pageCoverResponse'
- type: 'null'
description: The cover of the database.
url:
type: string
description: The URL of the database.
public_url:
oneOf:
- type: string
- type: 'null'
description: The public URL of the database if it is publicly accessible.
additionalProperties: false
required:
- object
- id
- title
- description
- parent
- is_inline
- in_trash
- is_locked
- created_time
- last_edited_time
- data_sources
- icon
- cover
- url
- public_url
error_api_400:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- invalid_json
- invalid_request_url
- invalid_request
- missing_version
- validation_error
status:
const: 400
required:
- code
- status
additionalProperties: false
error_api_401:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- unauthorized
status:
const: 401
required:
- code
- status
additionalProperties: false
error_api_403:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- restricted_resource
status:
const: 403
required:
- code
- status
additionalProperties: false
error_api_404:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- object_not_found
status:
const: 404
required:
- code
- status
additionalProperties: false
error_api_409:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- conflict_error
status:
const: 409
required:
- code
- status
additionalProperties: false
error_api_429:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- rate_limited
status:
const: 429
required:
- code
- status
additionalProperties: false
error_api_500:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- internal_server_error
status:
const: 500
required:
- code
- status
additionalProperties: false
error_api_503:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- service_unavailable
status:
const: 503
required:
- code
- status
additionalProperties: false
error_api_504:
allOf:
- $ref: '#/components/schemas/publicApiCommonErrorResponse'
- type: object
properties:
code:
enum:
- gateway_timeout
status:
const: 504
required:
- code
- status
additionalProperties: false
idResponse:
type: string
format: uuid
richTextItemResponse:
allOf:
- $ref: '#/components/schemas/richTextItemResponseCommon'
- oneOf:
- $ref: '#/components/schemas/textRichTextItemResponse'
- $ref: '#/components/schemas/mentionRichTextItemResponse'
- $ref: '#/components/schemas/equationRichTextItemResponse'
parentOfDatabaseResponse:
oneOf:
- $ref: '#/components/schemas/pageIdParentForBlockBasedObjectResponse'
- $ref: '#/components/schemas/workspaceParentForBlockBasedObjectResponse'
- $ref: '#/components/schemas/databaseParentResponse'
- $ref: '#/components/schemas/blockIdParentForBlockBasedObjectResponse'
dataSourceReferenceResponse:
type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the data source.
name:
type: string
description: The name of the data source.
additionalProperties: false
required:
- id
- name
pageIconResponse:
oneOf:
- $ref: '#/components/schemas/emojiPageIconResponse'
- $ref: '#/components/schemas/filePageIconResponse'
- $ref: '#/components/schemas/externalPageIconResponse'
- $ref: '#/components/schemas/customEmojiPageIconResponse'
- $ref: '#/components/schemas/iconPageIconResponse'
pageCoverResponse:
oneOf:
- $ref: '#/components/schemas/filePageCoverResponse'
- $ref: '#/components/schemas/externalPageCoverResponse'
publicApiCommonErrorResponse:
type: object
properties:
object:
const: error
message:
type: string
additional_data:
type: object
additionalProperties:
oneOf:
- type: string
- type: array
items:
type: string
required:
- object
- message
richTextItemResponseCommon:
type: object
properties:
plain_text:
type: string
description: The plain text content of the rich text object, without any styling.
href:
oneOf:
- type: string
- type: 'null'
description: A URL that the rich text object links to or mentions.
annotations:
$ref: '#/components/schemas/annotationResponse'
description: >-
All rich text objects contain an annotations object that sets the
styling for the rich text.
additionalProperties: false
required:
- plain_text
- href
- annotations
textRichTextItemResponse:
type: object
properties:
type:
type: string
const: text
description: Always `text`
text:
type: object
properties:
content:
type: string
maxLength: 2000
description: The actual text content of the text.
link:
oneOf:
- type: object
properties:
url:
type: string
examples:
- https://www.notion.com
description: The URL of the link.
additionalProperties: false
required:
- url
- type: 'null'
description: >-
An object with information about any inline link in this text,
if included.
additionalProperties: false
required:
- content
- link
description: >-
If a rich text object's type value is `text`, then the corresponding
text field contains an object including the text content and any
inline link.
required:
- type
- text
title: Text
mentionRichTextItemResponse:
type: object
properties:
type:
type: string
const: mention
description: Always `mention`
mention:
oneOf:
- type: object
properties:
type:
type: string
const: user
description: Always `user`
user:
$ref: '#/components/schemas/userValueResponse'
description: Details of the user mention.
additionalProperties: false
required:
- type
- user
title: User
- type: object
properties:
type:
type: string
const: date
description: Always `date`
date:
$ref: '#/components/schemas/dateResponse'
description: Details of the date mention.
additionalProperties: false
required:
- type
- date
title: Date
- type: object
properties:
type:
type: string
const: link_preview
description: Always `link_preview`
link_preview:
$ref: '#/components/schemas/linkPreviewMentionResponse'
description: Details of the link preview mention.
additionalProperties: false
required:
- type
- link_preview
title: Link Preview
- type: object
properties:
type:
type: string
const: link_mention
description: Always `link_mention`
link_mention:
$ref: '#/components/schemas/linkMentionResponse'
description: Details of the link mention.
additionalProperties: false
required:
- type
- link_mention
title: Link Mention
- type: object
properties:
type:
type: string
const: page
description: Always `page`
page:
type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the page in the mention.
additionalProperties: false
required:
- id
description: Details of the page mention.
additionalProperties: false
required:
- type
- page
title: Page
- type: object
properties:
type:
type: string
const: database
description: Always `database`
database:
type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the database in the mention.
additionalProperties: false
required:
- id
description: Details of the database mention.
additionalProperties: false
required:
- type
- database
title: Database
- type: object
properties:
type:
type: string
const: template_mention
description: Always `template_mention`
template_mention:
$ref: '#/components/schemas/templateMentionResponse'
description: Details of the template mention.
additionalProperties: false
required:
- type
- template_mention
title: Template Mention
- type: object
properties:
type:
type: string
const: custom_emoji
description: Always `custom_emoji`
custom_emoji:
$ref: '#/components/schemas/customEmojiResponse'
description: Details of the custom emoji mention.
additionalProperties: false
required:
- type
- custom_emoji
title: Custom Emoji
description: >-
Mention objects represent an inline mention of a database, date,
link preview mention, page, template mention, or user. A mention is
created in the Notion UI when a user types `@` followed by the name
of the reference.
required:
- type
- mention
title: Mention
equationRichTextItemResponse:
type: object
properties:
type:
type: string
const: equation
description: Always `equation`
equation:
type: object
properties:
expression:
type: string
examples:
- e=mc^2
description: A KaTeX compatible string.
additionalProperties: false
required:
- expression
description: >-
Notion supports inline LaTeX equations as rich text objects with a
type value of `equation`.
required:
- type
- equation
title: Equation
pageIdParentForBlockBasedObjectResponse:
type: object
properties:
type:
type: string
const: page_id
description: The parent type.
page_id:
$ref: '#/components/schemas/idResponse'
description: The ID of the parent page.
additionalProperties: false
required:
- type
- page_id
workspaceParentForBlockBasedObjectResponse:
type: object
properties:
type:
type: string
const: workspace
description: The parent type.
workspace:
type: boolean
const: true
description: Always true for workspace parent.
additionalProperties: false
required:
- type
- workspace
databaseParentResponse:
type: object
properties:
type:
type: string
const: database_id
description: The parent type.
database_id:
$ref: '#/components/schemas/idResponse'
description: The ID of the parent database.
additionalProperties: false
required:
- type
- database_id
blockIdParentForBlockBasedObjectResponse:
type: object
properties:
type:
type: string
const: block_id
description: The parent type.
block_id:
$ref: '#/components/schemas/idResponse'
description: The ID of the parent block.
additionalProperties: false
required:
- type
- block_id
emojiPageIconResponse:
type: object
properties:
type:
type: string
const: emoji
description: Type of icon. In this case, an emoji.
emoji:
$ref: '#/components/schemas/emojiRequest'
description: The emoji character used as the icon.
additionalProperties: false
required:
- type
- emoji
title: Emoji
filePageIconResponse:
type: object
properties:
type:
type: string
const: file
description: Type of icon. In this case, a file.
file:
$ref: '#/components/schemas/internalFileResponse'
description: The file URL for the icon.
additionalProperties: false
required:
- type
- file
title: File
externalPageIconResponse:
type: object
properties:
type:
type: string
const: external
description: Type of icon. In this case, an external URL.
external:
type: object
properties:
url:
type: string
description: The URL of the external file or resource.
additionalProperties: false
required:
- url
description: The external URL for the icon.
additionalProperties: false
required:
- type
- external
title: External
customEmojiPageIconResponse:
type: object
properties:
type:
type: string
const: custom_emoji
description: Type of icon. In this case, a custom emoji.
custom_emoji:
$ref: '#/components/schemas/customEmojiResponse'
description: The custom emoji details for the icon.
additionalProperties: false
required:
- type
- custom_emoji
title: Custom Emoji
iconPageIconResponse:
type: object
properties:
type:
type: string
const: icon
description: Type of icon. In this case, a Notion native icon.
icon:
$ref: '#/components/schemas/noticonIconResponse'
description: The Notion native icon, specified by name and color.
additionalProperties: false
required:
- type
- icon
title: Icon
filePageCoverResponse:
type: object
properties:
type:
type: string
const: file
description: Type of cover. In this case, a file.
file:
$ref: '#/components/schemas/internalFileResponse'
description: The file URL for the cover.
additionalProperties: false
required:
- type
- file
title: File
externalPageCoverResponse:
type: object
properties:
type:
type: string
const: external
description: Type of cover. In this case, an external URL.
external:
type: object
properties:
url:
type: string
description: The URL of the external file or resource.
additionalProperties: false
required:
- url
description: The external URL for the cover.
additionalProperties: false
required:
- type
- external
title: External
annotationResponse:
type: object
properties:
bold:
type: boolean
italic:
type: boolean
strikethrough:
type: boolean
underline:
type: boolean
code:
type: boolean
color:
$ref: '#/components/schemas/apiColor'
additionalProperties: false
required:
- bold
- italic
- strikethrough
- underline
- code
- color
userValueResponse:
oneOf:
- $ref: '#/components/schemas/partialUserObjectResponse'
- $ref: '#/components/schemas/userObjectResponse'
dateResponse:
type: object
properties:
start:
type: string
format: date
description: The start date of the date object.
end:
oneOf:
- type: string
format: date
- type: 'null'
description: The end date of the date object, if any.
time_zone:
oneOf:
- $ref: '#/components/schemas/timeZoneRequest'
- type: 'null'
description: The time zone of the date object.
additionalProperties: false
required:
- start
- end
- time_zone
linkPreviewMentionResponse:
type: object
properties:
url:
type: string
description: The URL of the link preview mention.
additionalProperties: false
required:
- url
linkMentionResponse:
type: object
properties:
href:
type: string
description: The href of the link mention.
title:
type: string
description: The title of the link.
description:
type: string
description: The description of the link.
link_author:
type: string
description: The author of the link.
link_provider:
type: string
description: The provider of the link.
thumbnail_url:
type: string
description: The thumbnail URL of the link.
icon_url:
type: string
description: The icon URL of the link.
iframe_url:
type: string
description: The iframe URL of the link.
height:
type: integer
description: The height of the link preview iframe.
padding:
type: integer
description: The padding of the link preview iframe.
padding_top:
type: integer
description: The top padding of the link preview iframe.
additionalProperties: false
required:
- href
templateMentionResponse:
oneOf:
- $ref: '#/components/schemas/templateMentionDateTemplateMentionResponse'
- $ref: '#/components/schemas/templateMentionUserTemplateMentionResponse'
customEmojiResponse:
type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the custom emoji.
name:
type: string
description: The name of the custom emoji.
url:
type: string
description: The URL of the custom emoji.
additionalProperties: false
required:
- id
- name
- url
emojiRequest:
type: string
internalFileResponse:
type: object
properties:
url:
type: string
description: The URL of the file.
expiry_time:
type: string
format: date-time
description: The time when the URL will expire.
additionalProperties: false
required:
- url
- expiry_time
noticonIconResponse:
type: object
properties:
name:
$ref: '#/components/schemas/noticonName'
description: >-
The name of the Notion icon (e.g. pizza, meeting, home). See the
Notion icon picker for valid names.
color:
$ref: '#/components/schemas/noticonColor'
description: >-
The color variant of the icon. Valid values: gray, lightgray, brown,
yellow, orange, green, blue, purple, pink, red.
additionalProperties: false
required:
- name
- color
apiColor:
type: string
enum:
- default
- gray
- brown
- orange
- yellow
- green
- blue
- purple
- pink
- red
- default_background
- gray_background
- brown_background
- orange_background
- yellow_background
- green_background
- blue_background
- purple_background
- pink_background
- red_background
description: >-
One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`,
`purple`, `pink`, `red`, `default_background`, `gray_background`,
`brown_background`, `orange_background`, `yellow_background`,
`green_background`, `blue_background`, `purple_background`,
`pink_background`, `red_background`
partialUserObjectResponse:
type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
object:
type: string
const: user
description: Always `user`
additionalProperties: false
required:
- id
- object
userObjectResponse:
allOf:
- $ref: '#/components/schemas/userObjectResponseCommon'
- oneOf:
- $ref: '#/components/schemas/personUserObjectResponse'
- $ref: '#/components/schemas/botUserObjectResponse'
timeZoneRequest:
type: string
templateMentionDateTemplateMentionResponse:
type: object
properties:
type:
type: string
const: template_mention_date
description: Always `template_mention_date`
template_mention_date:
type: string
enum:
- today
- now
description: The date of the template mention.
additionalProperties: false
required:
- type
- template_mention_date
title: Template Mention Date
templateMentionUserTemplateMentionResponse:
type: object
properties:
type:
type: string
const: template_mention_user
description: Always `template_mention_user`
template_mention_user:
type: string
const: me
description: The user of the template mention.
additionalProperties: false
required:
- type
- template_mention_user
title: Template Mention User
noticonName:
type: string
examples:
- pizza
- meeting
- home
- star
- robot
noticonColor:
type: string
enum:
- gray
- lightgray
- brown
- yellow
- orange
- green
- blue
- purple
- pink
- red
description: >-
One of: `gray`, `lightgray`, `brown`, `yellow`, `orange`, `green`,
`blue`, `purple`, `pink`, `red`
userObjectResponseCommon:
type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the user.
object:
type: string
const: user
description: The user object type name.
name:
oneOf:
- type: string
- type: 'null'
description: The name of the user.
avatar_url:
oneOf:
- type: string
- type: 'null'
description: The avatar URL of the user.
additionalProperties: false
required:
- id
- object
- name
- avatar_url
personUserObjectResponse:
type: object
properties:
type:
type: string
const: person
description: Indicates this user is a person.
person:
type: object
properties:
email:
type: string
description: The email of the person.
additionalProperties: false
description: Details about the person, when the `type` of the user is `person`.
required:
- type
- person
title: Person
botUserObjectResponse:
type: object
properties:
type:
type: string
const: bot
description: Indicates this user is a bot.
bot:
oneOf:
- $ref: '#/components/schemas/emptyObject'
- $ref: '#/components/schemas/botInfoResponse'
description: Details about the bot, when the `type` of the user is `bot`.
required:
- type
- bot
title: Bot
emptyObject:
type: object
properties: {}
additionalProperties: false
botInfoResponse:
type: object
properties:
owner:
oneOf:
- type: object
properties:
type:
type: string
const: user
description: Always `user`
user:
oneOf:
- type: object
properties:
id:
$ref: '#/components/schemas/idResponse'
description: The ID of the user.
object:
type: string
const: user
description: The user object type name.
name:
oneOf:
- type: string
- type: 'null'
description: The name of the user.
avatar_url:
oneOf:
- type: string
- type: 'null'
description: The avatar URL of the user.
type:
type: string
const: person
description: The type of the user.
person:
type: object
properties:
email:
type: string
description: The email of the person.
additionalProperties: false
description: The person info of the user.
additionalProperties: false
required:
- id
- object
- name
- avatar_url
- type
- person
- $ref: '#/components/schemas/partialUserObjectResponse'
description: >-
Details about the owner of the bot, when the `type` of the
owner is `user`. This means the bot is for a integration.
additionalProperties: false
required:
- type
- user
title: User
- type: object
properties:
type:
type: string
const: workspace
description: Always `workspace`
workspace:
type: boolean
const: true
description: >-
Details about the owner of the bot, when the `type` of the
owner is `workspace`. This means the bot is for an internal
integration.
additionalProperties: false
required:
- type
- workspace
title: Workspace
description: Details about the owner of the bot.
workspace_id:
type: string
description: The ID of the bot's workspace.
workspace_limits:
type: object
properties:
max_file_upload_size_in_bytes:
type: integer
minimum: 0
description: The maximum allowable size of a file upload, in bytes
additionalProperties: false
required:
- max_file_upload_size_in_bytes
description: Limits and restrictions that apply to the bot's workspace
workspace_name:
oneOf:
- type: string
- type: 'null'
description: The name of the bot's workspace.
additionalProperties: false
required:
- owner
- workspace_id
- workspace_limits
- workspace_name
parameters:
notionVersion:
name: Notion-Version
in: header
required: true
schema:
enum:
- '2026-03-11'
description: >-
The [API version](/reference/versioning) to use for this request. The
latest version is `2026-03-11`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````