Skip to main content
Use the property-item endpoint to read all the values in a property that refers to many pages or people. This guide also handles single values, such as Status, and waits for a rollup’s final result.

Get the page and property IDs

Your connection needs read content capabilities and access to the page. For relations, formulas, and rollups, share the related databases too. Retrieve the page. Find the property by name in its properties object, then copy its id. Pass that ID as returned, including any URL encoding.

Set up the request

Use the JavaScript SDK in a server-side Node.js project. Set NOTION_API_KEY, NOTION_PAGE_ID, and NOTION_PROPERTY_ID in your environment. Tokens must not appear in browser page source, client bundles, or public repositories. The cURL example reads one response. The JavaScript example reads every response and prints the items. Save it as read-property.mjs and run node read-property.mjs.

Use the result

For a single property item, read the field named by type. For example, a Status value is in status, and it can be null. For a list, process every item in results. A title or text item contains one rich text object. A people item contains one user. A relation item contains one page reference. For a calculated rollup, use property_item.rollup from the final response. For show_original, use the printed items; the final metadata has an empty array. See Rollup response rules.

Handle failures

A 403 means the connection lacks a required capability. A 404 can mean the page or property is missing, or that your connection lacks access. Check the IDs and sharing settings. The SDK retries rate-limit errors by default. If retries fail, the script exits with an error. For unsupported formula or rollup results, review the calculation limits. Repeating the same request does not remove those limits.