はじめに

kintoneで一定件数を超えるレコードを扱うとき、
「カーソルAPI（/records/cursor）」を使って全件取得することがあります。

とても便利なAPIですが、実際の運用環境では 意外な落とし穴 があります。
この記事では、その仕組みと注意点、そして安定して全件取得するための代替設計について紹介します。

1. カーソルAPIとは？

kintoneの /records/cursor は、大量のレコードを分割して取得できるAPIです。

カーソルを作成する（取得条件・フィールドを指定）
カーソルを使って複数回に分けてレコードを取得する
最後にカーソルを削除する

これにより、10万件を超えるようなデータも安定して扱えるようになります。

2. よくあるエラー：「カーソル上限に達しました」

実際の現場では、次のようなエラーに遭遇することがあります。

作成できるカーソルの上限に達しているため、カーソルを作成できません。
不要なカーソルを削除するか、しばらく経ってから再実行してください。

これは同時に作成できるカーソル数が最大10件までという制約によるものです。

3. なぜ落とし穴になるのか？

他のプラグインやカスタマイズが同時にカーソルを作成している
一度に複数の一覧画面やタブを開いている
通信途中でカーソル削除処理が行われなかった

これらが重なると、知らないうちに上限10件を超え、エラーが発生します。

開発者が「自分のコードでカーソルを10個も作っていないのに」と思っても、
他のカスタマイズの影響で起きるケースが多いのが厄介な点です。

4. 回避策と判断基準

まず前提として、カーソルAPIの上限エラーが出た場合、
最初にすべきことはカーソルの削除 です。

カーソルはサーバー側に「セッション」として保持されるため、
放置すると他の処理も影響を受けます。
使い終わったら必ず削除する、もしくは時間経過で自動削除を待ちます。

const body = {
  id: '9a9716fe-1394-4677-a1c7-2199a5d28215'
};

await kintone.api(kintone.api.url('/k/v1/records/cursor.json', true), 'DELETE', body);

📍 本当にカーソルが必要か？

ここが最大の落とし穴です。

カーソルAPIは「大量データの一括取得」に特化したAPIであり、
「ただレコードを取得したい」ケースには不向きです。

用途	カーソルAPIの適正	推奨代替
一覧画面で最新100件を取得	❌ 不向き	通常の /k/v1/records.json
集計やグラフ描画（数千件単位）	△ 要検討	offset / limit + 分割処理
全件エクスポート（数万件〜）	✅ 有効	カーソルAPIを明示的に管理
定期バッチ・夜間処理	✅ 有効	カーソル作成 → 取得 → 削除を順守

判断の目安

カーソルAPIは「制御できる単独スクリプト」であれば安全です。
逆に、複数のプラグインや画面操作が絡む環境ではリスクが高いです。

✅ 使ってよい場面：バッチ処理・定期タスク・単独アプリ
⚠️ 避けたい場面：画面カスタマイズ・複数プラグイン共存環境
🚫 不適切な場面：単に最新データを一覧取得したい場合

6. まとめ：便利さと責任のバランス

🔸 カーソルAPIは大量データ処理のための“強力な道具”
⚠️ だが、使うたびにサーバー側にセッションを作る
🧩 そのため、「本当に必要か」を見極めることが最も重要