はじめに
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は大量データ処理のための“強力な道具”
- ⚠️ だが、使うたびにサーバー側にセッションを作る
- 🧩 そのため、「本当に必要か」を見極めることが最も重要