Retrieves a page object using the specified ID. Returns either a full page object or a partial page object, depending on the integration’s permissions.
Method Signature
notion.pages.retrieve(args: GetPageParameters): Promise<PageObjectResponse | PartialPageObjectResponse>
Parameters
The ID of the page to retrieve (with or without dashes).Example: "897e5a76-ae52-4b48-9fdf-e71f5945d1af" or "897e5a76ae524b489fdfe71f5945d1af"
An array of property IDs to filter the response. Only the specified properties will be included in the response.Note: If a page doesn’t have a property, it won’t be included in the filtered response.Example: ["title", "abc123", "def456"]
Bearer token for authentication. Overrides the client-level authentication.
Response
ISO 8601 timestamp when the page was created
ISO 8601 timestamp when the page was last edited
Whether the page is archived
Whether the page is in trash
Whether the page is locked from editing in the Notion app UI
The URL of the Notion page
The public URL if the page has been published to the web, otherwise null
Information about the page’s parent (database, page, workspace, or block)
Property values of the page. Each property is keyed by its name and contains type-specific data.
Page icon (emoji, external URL, file, or custom emoji)
Page cover image (external URL or file)
User who created the page
User who last edited the page
Examples
Basic Page Retrieval
const page = await notion.pages.retrieve({
page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})
console.log("Page title:", page.properties.Name.title[0].plain_text)
console.log("Created:", page.created_time)
console.log("URL:", page.url)
Retrieve with Property Filtering
Filter the response to only include specific properties:
const page = await notion.pages.retrieve({
page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
filter_properties: ["title", "abc123", "def456"],
})
// Only the filtered properties will be present in page.properties
Type-Safe Property Access
import { isFullPage } from "@notionhq/client"
const response = await notion.pages.retrieve({
page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})
// Use type guard to access full page properties
if (isFullPage(response)) {
console.log("Page URL:", response.url)
console.log("Is locked:", response.is_locked)
// Access properties with type safety
const titleProp = response.properties.Name
if (titleProp.type === "title") {
console.log("Title:", titleProp.title[0]?.plain_text)
}
} else {
// Partial page - limited access
console.log("Page ID:", response.id)
}
import { extractPageId } from "@notionhq/client"
const pageUrl = "https://notion.so/My-Page-897e5a76ae524b489fdfe71f5945d1af"
const pageId = extractPageId(pageUrl)
const page = await notion.pages.retrieve({
page_id: pageId,
})
Access Different Property Types
const page = await notion.pages.retrieve({
page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})
if (isFullPage(page)) {
// Title property
const titleProp = page.properties.Name
if (titleProp.type === "title") {
console.log("Title:", titleProp.title[0]?.plain_text)
}
// Select property
const statusProp = page.properties.Status
if (statusProp.type === "select") {
console.log("Status:", statusProp.select?.name)
}
// Date property
const dateProp = page.properties["Due Date"]
if (dateProp.type === "date") {
console.log("Due:", dateProp.date?.start)
}
// Checkbox property
const checkboxProp = page.properties.Completed
if (checkboxProp.type === "checkbox") {
console.log("Completed:", checkboxProp.checkbox)
}
// People property
const peopleProp = page.properties.Assignee
if (peopleProp.type === "people") {
console.log("Assigned to:", peopleProp.people.length, "people")
}
}
Check Page Metadata
const page = await notion.pages.retrieve({
page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
})
if (isFullPage(page)) {
console.log("Archived:", page.archived)
console.log("In trash:", page.in_trash)
console.log("Locked:", page.is_locked)
console.log("Public URL:", page.public_url || "Not published")
// Check parent type
if (page.parent.type === "database_id") {
console.log("Parent database:", page.parent.database_id)
} else if (page.parent.type === "page_id") {
console.log("Parent page:", page.parent.page_id)
}
}
Error Handling
import { APIResponseError, APIErrorCode } from "@notionhq/client"
try {
const page = await notion.pages.retrieve({
page_id: "invalid-id",
})
} catch (error) {
if (APIResponseError.isAPIResponseError(error)) {
if (error.code === APIErrorCode.ObjectNotFound) {
console.error("Page not found or no access")
} else if (error.code === APIErrorCode.Unauthorized) {
console.error("Invalid or missing authentication")
} else {
console.error("API error:", error.message)
}
} else {
console.error("Unexpected error:", error)
}
}
See Also
