Notion API v3 – nested database relations return only IDs, not full objects

Resolving Relation Properties in Notion API

The Notion API returns relation properties as an array of page IDs rather than expanded objects. This behavior is intentional and consistent with the API's design; there are currently no undocumented parameters or "deep load" flags to automatically expand nested relation objects into full page data within a single request.

The Recommended Implementation Pattern

To retrieve the full details of related pages without incurring excessive latency or hitting rate limits, developers should implement a batch-and-cache strategy rather than performing a request for every single ID encountered.

1. Extract Unique IDs: Collect all page IDs from the relation properties of your initial query results into a unique set.
2. Concurrent Retrieval: Use asynchronous requests to fetch the required pages. Since the Notion API does not provide a "bulk get" endpoint for arbitrary page IDs, you must call the Retrieve a Page endpoint for each unique ID.
3. Local Mapping: Store these retrieved objects in a local map (dictionary) where the key is the Page ID.
4. Client-Side Join: Map the IDs in your original database response to the objects in your local map to reconstruct the relational view for the UI.

Performance and Rate Limit Considerations

Because each related page requires a separate API call, high-volume relational data can quickly trigger 429 Too Many Requests errors. To mitigate this, consider the following:

• Caching: Implement a short-term cache (e.g., Redis or an in-memory store) for related page data to avoid refetching the same entities across different user sessions.
• Request Throttling: Use a concurrency limit (e.g., 5–10 simultaneous requests) to stay within Notion's rate limits.
• Selective Fetching: Only resolve relations that are visible in the current view or required for the immediate business logic.

Verification Steps

You can verify this behavior by executing a GET request to the /v1/databases/{database_id}/query endpoint. Inspect the properties object for any property of type relation; you will observe that the id field is present, but the properties of that related page are absent.

Diagnostic Detail Required: To provide a more optimized fetching strategy, please specify if you are retrieving relations for a single page or aggregating relations across a large result set of multiple pages.