pages.properties.retrieve

Retrieve a specific page property item

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

Show Fields

type · string

The property type (e.g., "title", "rich_text")

id · string

The property ID

next_url · string | null

URL to fetch the next page of results, or null if no more pages

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

Related Methods

• pages.retrieve - Retrieve a full page with all properties
• pages.update - Update page properties
• Pagination helpers - Utilities for paginating API responses

See Also

• Notion API: Retrieve a page property item
• Property value objects