Skip to main content
Retrieves a specific property item from a page. This is useful for accessing long property values (like long text or large relation lists) that may be paginated.

​
Method Signature

notion.pages.properties.retrieve(args: GetPagePropertyParameters): Promise<PropertyItemObjectResponse | PropertyItemListResponse>

​
Parameters

​
page_id
string
required
The ID of the page containing the property (with or without dashes).
​
property_id
string
required
The ID or name of the property to retrieve. You can use either:
  • The property ID (e.g., "title", "%3E%5DWj")
  • The property name (e.g., "Name", "Status")
​
start_cursor
string
Used for pagination. If the property has more items than fit in a single response, use this cursor to fetch the next page of results.
​
page_size
number
The number of items to return per page. Maximum is 100 (default: 100).
​
auth
string
Bearer token for authentication. Overrides the client-level authentication.

​
Response

​
PropertyItemObjectResponse

For simple properties (number, select, checkbox, etc.), returns a single property item:
​
object
string
Always "property_item"
​
id
string
The ID of the property
​
type
string
The type of the property (e.g., "number", "select", "date")
​
[type]
any
The property value, keyed by the property type. For example, if type is "number", the value is in the number field.

​
PropertyItemListResponse

For paginated properties (title, rich_text, people, relation, rollup), returns a list response:
​
type
string
Always "property_item"
​
property_item
object
Contains the property type, ID, and pagination info
​
results
array
Array of property items for this page
​
next_cursor
string | null
Cursor to use for fetching the next page, or null if no more pages
​
has_more
boolean
Whether there are more results available

​
Examples

​
Retrieve a Simple Property

// Retrieve a select property
const property = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Status",
})

if (property.type === "select") {
  console.log("Status:", property.select?.name)
}

​
Retrieve a Title Property

const property = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "title",
})

if (property.object === "list") {
  // Title properties are paginated
  console.log("Title items:", property.results.length)
  console.log("Has more:", property.has_more)
}

​
Retrieve Different Property Types

// Number property
const numberProp = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Score",
})
if (numberProp.type === "number") {
  console.log("Score:", numberProp.number)
}

// Date property
const dateProp = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Due Date",
})
if (dateProp.type === "date") {
  console.log("Due date:", dateProp.date?.start)
}

// Checkbox property
const checkboxProp = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Completed",
})
if (checkboxProp.type === "checkbox") {
  console.log("Completed:", checkboxProp.checkbox)
}

​
Paginate Through Property Items

let cursor: string | undefined = undefined
const allItems = []

do {
  const response = await notion.pages.properties.retrieve({
    page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
    property_id: "Relation",
    start_cursor: cursor,
    page_size: 50,
  })
  
  if (response.object === "list") {
    allItems.push(...response.results)
    cursor = response.next_cursor || undefined
  } else {
    break
  }
} while (cursor)

console.log("Total items:", allItems.length)

​
Retrieve Rich Text Property

const property = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Description",
})

if (property.object === "list" && property.results.length > 0) {
  const richTextItem = property.results[0]
  if (richTextItem.type === "rich_text") {
    console.log("Description:", richTextItem.rich_text.plain_text)
  }
}

​
Retrieve People Property

const property = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Assignees",
})

if (property.object === "list") {
  for (const item of property.results) {
    if (item.type === "people" && item.people) {
      console.log("Person ID:", item.people.id)
    }
  }
}

​
Retrieve Rollup Property

const property = await notion.pages.properties.retrieve({
  page_id: "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  property_id: "Total",
})

if (property.type === "rollup") {
  if (property.rollup.type === "number") {
    console.log("Total:", property.rollup.number)
  } else if (property.rollup.type === "array") {
    console.log("Items:", property.rollup.array.length)
  }
}

​
Helper Function for Pagination

async function getAllPropertyItems(
  pageId: string,
  propertyId: string
): Promise<PropertyItemObjectResponse[]> {
  const items: PropertyItemObjectResponse[] = []
  let cursor: string | undefined = undefined
  
  do {
    const response = await notion.pages.properties.retrieve({
      page_id: pageId,
      property_id: propertyId,
      start_cursor: cursor,
    })
    
    if (response.object === "list") {
      items.push(...response.results)
      cursor = response.next_cursor || undefined
    } else {
      // Single item response
      items.push(response)
      break
    }
  } while (cursor)
  
  return items
}

// Usage
const items = await getAllPropertyItems(
  "897e5a76-ae52-4b48-9fdf-e71f5945d1af",
  "Comments"
)
console.log("Retrieved", items.length, "items")

​
Property Types

The following property types are supported:
  • Simple properties (single item response):
    • number, url, select, multi_select, status, date, email, phone_number
    • checkbox, files, created_by, created_time, last_edited_by, last_edited_time
    • formula, button, unique_id, verification, place
  • Paginated properties (list response):
    • title, rich_text, people, relation, rollup

​
Important Notes

For properties with long values (like long text or many relations), the response may be paginated. Check for has_more and use next_cursor to fetch additional pages.
You can use either the property ID or property name for the property_id parameter. Property IDs are more stable if you rename properties frequently.
Some computed properties (like rollup and formula) may take time to calculate. The SDK will return the current value, which may be outdated if the source data changed recently.

​
Use Cases

  • Access long text: Retrieve full content of rich text properties that exceed the normal page limit
  • List relations: Get all related pages for a relation property
  • Fetch user lists: Retrieve all people assigned to a property
  • Property-specific queries: Get a single property without fetching the entire page

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us