Notion API database query pagination limits and result bounding

Pagination Limits and Result Bounding

The Notion API does not provide a total result count in the response body of a database query. To determine the total size of a dataset, you must iteratively request pages and accumulate the results until the has_more property returns false.

Technical Constraints

• Maximum Page Size: The enforced maximum page_size is 100 records per request. This limit is consistent across the database query endpoints.
• Cursor Stability: While a deterministic sort helps maintain order, cursor progression is not strictly stable against concurrent mutations. Because the API uses a snapshot-like cursor rather than a fixed integer offset, adding or modifying records between requests can cause items to shift, potentially leading to duplicate entries or missed records in the result set.

Implementation Steps for Bounding Results

To bound or count your results, implement the following client-side logic:

1. Send an initial POST request to /v1/databases/{database_id}/query with your desired page_size (up to 100).
2. Store the returned results and check the has_more boolean.
3. If has_more is true, extract the next_cursor and pass it as the start_cursor in the subsequent request.
4. Repeat until has_more is false or your specific bound (e.g., a maximum record limit) is reached.

Verification Method

To verify your pagination logic is functioning correctly, you can use a small page_size to force multiple round-trips:

# Example: Requesting 1 record at a time to test cursor progression
curl -X POST https://api.notion.com/v1/databases/{database_id}/query \
  -H "Authorization: Bearer {token}" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 1}'

Confirm that the next_cursor from the first response successfully retrieves the second record when passed as the start_cursor.

Required Diagnostic Detail

Are you performing these queries against a database with frequent concurrent writes? If so, the risk of result instability increases, and you may need to implement a deduplication strategy based on the page ID.