はじめに

hkob の雑記録の第474回目(連続47日目)は、Developer site の ChangeLog が 2 件更新されていたので、それを解説します。

Data source and view query pagination limit

4/20 に pagination の limit について告知がありました。

データソースおよびビューのクエリにおけるページネーション上限

データソースをクエリする、ビューのクエリを作成する、ビューのクエリ結果を取得するの各エンドポイントでは、1 回のクエリあたりのページネーション深度の最大値が 10,000 件に制限されるようになりました。クエリがこの上限を超える行数に一致した場合、レスポンスには新たに request_status フィールドが含まれます。
{
  "request_status": {
    "type": "incomplete",
    "incomplete_reason": "query_result_limit_reached"
  }
}
大規模なデータソースに対して、これらのエンドポイントをポーリングして一致する全行を順に取得していたインテグレーションは、request_status.type === "incomplete" を確認し、それに応じて処理を変更してください。この制限は、各クエリで消費されるサーバー側リソースに上限を設けることで、すべての API 利用者にとっての信頼性を向上させます。

大規模なデータソース内のすべてのページを処理する必要がある場合は、次を推奨します。

データソースフィルターを使う、またはビューのフィルター／ソート設定を絞り込んで、結果件数を減らす（例：last_edited_time でフィルターし、最近変更されたページだけを取得する）。

定期的に全件をポーリングするのではなく、増分同期のためにインテグレーションの Webhook を設定する。

大きなデータソースを、複数の小さなデータソースに分割する。

基本的には全件取得ではなく、フィルタを使って制約するようにしてくださいとのことです。田原さんもこの件についてポストしていました。

NotionAPIの直近の仕様変更により、1つのクエリで10,000件を超えたデータ取得ができなくなりました。

作成日時やページIDの末尾文字をフィルターに使ってクエリを分割すれば10,000件を超えるデータも取得できます。https://t.co/QP2RkGxRjo pic.twitter.com/4p7caanJM1
— 田原聖悟 (@shogocat) 2026年4月25日

Improvements to pagination reliability for the Query a data source endpoint

もう一件は、Query a data source endpoint における pagination の reliability 向上です。

データソースをクエリするエンドポイントのページネーション信頼性が改善されました。

ページネーションカーソルにセッション識別子が埋め込まれるようになり、同一クエリに対する複数のページネーションセッションが重なった場合に断続的に発生していた 400 validation_error（"The start_cursor provided is invalid"）エラーが解消されました。

start_cursor パラメータは UUID に加えて不透明な文字列値も受け付けるようになりました。既存の UUID ベースのカーソルは引き続き動作します。バージョニングポリシーに記載のとおり、カーソルは常に不透明な値として扱い、next_cursor の値を解析・検証せずそのまま start_cursor として渡してください。

これまで next_cursor はだいたい次に読み込まれる page などの id を保持していました。しかし、今後は任意の識別子も付与させるようです。API 自体はクッキーなどのセッション情報を持たないので、偶然同じ next_cursor を保持する