Airtable APIで101件目以降が取得できないときoffsetを最後まで追う

AirtableのWeb APIでlist recordsを一度呼び出しても、テーブルの全レコードが返るとは限りません。Airtableの現行公式資料では、1回の応答は最大100件で、続きを取得する場合は応答に含まれるoffsetを次のリクエストのquery parameterとして渡します。offsetが次の応答に含まれなくなった時点でページングを終了します。ページ番号を1ずつ増やす方法でも、offsetを数値として計算する方法でもありません。

101件以上を扱う処理では、records配列を受け取ったら終わりにせず、offsetがある限り次ページを取りに行くループを作ります。さらに、filterByFormula、view、sortなどの条件と取得対象の定義をページ間で変えないようにし、重複や欠落を検知できる形で結果を保存します。ページングだけで複数リクエストを通じた固定スナップショットが保証されるとは考えず、取得中にレコードが追加・削除・更新される運用では後段で照合します。

100件は一回の応答上限

Airtableのlist records APIはページ単位で結果を返します。ページサイズは最大100件です。テーブルに100件を超える対象レコードがあれば、最初の応答にrecordsとoffsetが返されます。次のリクエストへそのoffsetを含めると次のページを取得でき、さらに続きがある場合は新しいoffsetが返ります。最後のページではoffsetが返らないため、その応答を処理したら終了です。

pageSizeを50にすれば1ページを小さくできますが、全件を取るためのページ数は増えます。pageSize=100でも全ページを自動で受信するわけではありません。maxRecordsは取得総数の上限として働くため、「全件」が必要な処理で100や任意の小さな数を指定すると、その件数で意図的に止まります。取得対象を制限したい場合だけ使い、全件取得の設定と取り違えないでください。

表は横にスクロールできます

項目	役割	注意点
records	今回のページで返ったレコード	0件かどうかだけで終端判定しない
pageSize	1ページに含める最大数	最大100。小さくするとリクエスト回数が増える
offset	続きのページを指すAPI応答値	次のリクエストへそのまま渡す。自分で作らない
maxRecords	取得全体の最大件数	指定値で終了するため、全件取得では設定を確認
filter / view / sort	取得対象と順序を定義	ページング中に変えると結果集合の解釈が崩れる

offsetを最後まで渡す

ページング処理の基本形は次のとおりです。

1. 最初のURLにbaseとtableを指定し、必要なfilter、view、sort、fields、pageSizeなどの条件を決める。

2. GETを実行し、HTTP statusとJSONを検証する。

3. records配列を受け取り、ページ内のレコードIDを記録して保存する。

4. JSONにoffsetがあるか確認する。

5. offsetがあれば、同じ検索条件にoffsetを追加し、次のGETを実行する。

6. 次のページも同様にrecordsを保存し、応答ごとに返された新しいoffsetへ更新する。

7. offsetがなくなったらループを終了し、取得件数・重複・期待する対象条件を検証する。

offsetはサーバーが返した値です。ページ番号、レコード件数、最後のレコードIDから独自に生成しないでください。URLへ付ける際はHTTPクライアントのquery parameter機能を使い、値を適切にencodeします。offset内にスラッシュなどURLで特別な意味を持つ文字が含まれることがあるため、値を手作業で連結すると壊れるおそれがあります。認証情報をquery stringへ入れず、Authorization headerなど安全な認証方式を使用します。

概念上の疑似コードは次のようになります。

• query条件を一度だけ作る

• offsetを未設定で開始する

• response = listRecords(query条件, offset)

• response.recordsを追加または一時保存する

• response.offsetがあれば、同じ条件で次のリクエストへ進む

• response.offsetがなければ終了する

• 最後に件数・重複・失敗ページを検証する

各ページで返されたoffsetを、次のページから返されたoffsetへ置き換えます。最初のoffsetをすべての後続リクエストに再利用すると、同じページを取り続ける可能性があります。また、offsetを取得したあとにレスポンス全体を捨てたり、次のリクエストを呼ぶ処理を条件分岐の外へ置き忘れたりすると、最初の100件で処理が終わります。

件数で終わりを推測しない

100件ちょうど返ったページは、次ページがある場合も、テーブルの最後のページである場合もあります。したがって「100件未満なら終了」のような条件だけでは正しく判定できません。逆に、100件を受け取ったから必ず次ページがあるとも限りません。正式な終端条件は、応答にoffsetがあるかどうかです。

テーブルに501件ある例では、100件ずつのページが5回と、最後の1件を返すページが1回、合計6回のlist recordsリクエストが必要です。レコードがちょうど500件なら100件の応答が5回で、その後の応答にoffsetがなければ終了します。処理件数だけから次ページの有無を決めず、各レスポンスのoffsetを確認します。

表は横にスクロールできます

想定対象数	期待する取得ページ	確認点
0件	空のrecords、offsetなし	空結果を正常な0件とAPIエラーに分ける
1件	1ページ	1件保存され、offsetがなければ終了
100件	通常1ページ	100件でもoffsetがなければ終了
101件	100件＋1件	最初のoffsetを次のqueryへ渡せているか
200件	100件＋100件	2ページ目のoffset有無で終了を判定
201件	100件＋100件＋1件	最終offsetを見落としていないか

実装テストでは、100件未満だけでなく100、101、200、201件を含めます。特に101件で2ページ目へ進むか、200件で最後の100件を受け取ったあと重複が起きないかを確認します。1ページ目の応答をfixtureとして固定し、2ページ目で新しいoffsetが返るケースもテストします。

filter、view、sortを保つ

一回目と二回目で取得条件が異なると、全件集合としての意味が変わります。filterByFormulaで特定条件を付けているなら、すべてのページで同じ式を使います。viewを指定した場合も同じviewを使い、sortやfieldsを変える必要がないかを設計段階で決めてください。

レコードを取得している間に対象テーブルが編集される場合は注意が必要です。offsetページングだけから、複数リクエストを通じた完全な時点固定スナップショットを得られるとは限りません。追加・削除・並び替えが発生すると、記録したIDに重複や欠落がないか点検する必要があります。監査やバックアップ用途なら、取得開始・終了時刻を記録し、必要なら対象テーブルを編集停止できる時間に実行するか、終了後に変更検知の比較を行います。APIが保証していないスナップショット性を前提にしないでください。

offsetは再開用の自前ページ番号ではありません。途中停止時に保存したoffsetを後で再利用できると決めつけないでください。API応答がoffsetを受け付けない場合やデータが変わった場合は、そのページを安全に再開できるかを検証します。信頼できる再開仕様を確認できないときは、保存済みレコードIDで重複を除きながら最初から再取得する方が安全です。大量の出力を書き込むときは、ページ単位で一時保存し、各ページの完了状態を記録します。

API速度制限とページ数

ページごとにAPIリクエストが必要なため、数十ページを一気に同時実行すると速度制限に達する可能性があります。Airtable公式ヘルプでは、Web APIにbaseごとのリクエスト速度制限があり、月間API call上限はプランで異なると説明されています。これは1回のlist recordsの100件上限とは別の制約です。100件単位で取得できることを理由に、リクエストを並列に大量送信しないでください。

429が返った場合は、最新のAirtable公式API資料で待機方法を確認し、無理な固定間隔で再送しないようにします。現在の速度制限の値や月間枠は変わることがあるため、実装する日に公式ヘルプを再確認してください。プランの月間API call枠を使い切った場合と、短時間の速度制限を同じ問題として扱わないことも重要です。

ページ数からリクエスト数を概算できます。対象数が1,250件でpageSize 100なら、少なくとも13回のlist recordsリクエストが必要です。retryや追加照会で呼び出し数が増える場合もあります。大きな表を定期同期するなら必要なfieldsだけ要求し、頻度や対象recordを見直します。ただし、ページングを避けるために対象を意図せず絞り、必要なrecordを落とすことは避けてください。

欠落と重複を見つける検証

すべてのページがHTTP 200だったことは、全件が保存された証拠にはなりません。各record IDを収集し、次の条件を確認します。

• offsetが返っているすべての応答で次リクエストが実行された

• offsetがなくなった時点で停止した

• 同じrecord IDが複数ページに重複していない

• 保存records総数と一意ID数の差を調べた

• filter / view / sort / fieldsがページをまたいで同じである

• 取得失敗したページを成功扱いしていない

• rate limit後に同じoffsetから再開し、既に保存したページを重複登録していない

• テーブルが処理中に編集された可能性を記録した

• 必要なfieldが空であるケースとAPI取得漏れを区別した

「想定総数」は別途定義します。Airtableの画面で見える件数がviewで絞られているなら、APIで全テーブルを取得した件数とは一致しない場合があります。比較するのは同じbase・table・filter・view・対象時刻の集合です。応答に総件数が自動で付くと仮定せず、必要なら同一条件で件数を別途照合します。件数が一致しない場合も、すぐにoffsetの不具合と決めず、filter条件、アクセス可能範囲、処理中の更新を確認します。

よくある失敗と直し方

最初の100件で完了としている

原因は、records配列を保存したあとoffsetを確認していない、offsetがある場合に次requestを呼んでいない、または呼んでもresponse offsetを更新していないことです。成功レスポンスごとにrecordsとoffsetを同じページ状態として扱います。

offsetを手作業で作る

offsetは応答から受け取る文字列です。offset=100のように件数を入れても次ページ指定にはなりません。前回のrecord IDからtokenを組み立てる方法も使いません。

offset以外のquery条件を落とす

2回目のURLをoffsetだけで作り直すと、filterやviewが失われ、別のrecord集合が混ざることがあります。query parameterを辞書などで管理し、ページごとにoffsetだけを更新します。

maxRecordsを小さく設定する

たとえばmaxRecords=100に設定したままoffsetを最後まで追っても、総数が100件で止まります。取得総数を制限したい用途では正しい設定ですが、全件取得では意図を確認してください。

同時編集を見ない

API呼び出しの間にデータが変わると、一時点の完全な表として取得できたとは限りません。取得時間、filter条件、件数、一意IDを記録し、必要な場合は差分再照合を行います。

実装前後のチェックリスト

実装前：

1. base IDとtable IDを確認する。似たテーブル名を推測で使わない。

2. 全テーブルなのか、filter/viewで絞ったレコード集合なのかを決める。

3. fields、sort、pageSize、maxRecordsを決める。全件取得でmaxRecordsを誤設定していないか確認する。

4. 複数ページ分のAPI速度・月間call枠を見積もる。

5. API tokenをログやブラウザURLに含めない。

実装後：

1. 100件を超えるテストデータで実際に2ページ以上取得する。

2. 各応答のoffsetを受け渡したことを記録する。

3. 最終応答でoffsetが消えたら停止することを確認する。

4. record IDの重複、欠落、件数差を検証する。

5. 途中で429になった場合、ページを重複登録せず再開できることを確認する。

6. 処理中にテーブルが編集された場合は、その影響を報告する。

7. 取得結果を本番データへ反映する前に、同期先の一意性や上書き範囲を確認する。

まとめ：offsetが消えるまで同じ条件で繰り返す

Airtable APIで101件目以降を取得するには、最初の100件を受け取ったあと、応答のoffsetを次のlist recordsリクエストへ渡します。以後は毎回、新しい応答に含まれるoffsetへ更新し、offsetが返らなくなったら終わりです。件数が100未満かどうかや、ページ番号の計算では終了を判断しません。

ページングの間はfilter、view、sortなどの条件を保ち、maxRecordsが取得総数を不意に絞っていないか確認します。Airtableの速度制限も考慮し、429後の待機と再開方法を現行資料で確認します。取得完了後はrecord ID、件数、重複、欠落を照合します。テーブルの同時編集がある環境では、offsetだけで完全なスナップショットが保証されると決めつけないことが安全な全件取得の条件です。

Sources

• https://support.airtable.com/articles/6292134965-getting-started-with-airtable-s-web-api（新しいタブで開く）

• https://support.airtable.com/articles/7735693959-managing-api-call-limits-in-airtable（新しいタブで開く）

• https://airtable.com/developers/web/api/list-records（新しいタブで開く）

Editorial Notes

Fact status: Airtable公式Web API案内を2026-10-15に確認。ページあたり最大100件、返却offsetを次requestへ渡し、offsetがなくなれば終端という手順を照合。公式Helpでbase単位の速度制限とプラン別月間call枠を確認。record-set snapshot guaranteeやoffset期限は断定せず、並行編集時の再照合を実務上の注意として記載。Hands-on API testは未実施。Reader Jobはoffset loop、条件保持、件数・一意IDの検証まで完了する。