n8nのLoop Over Itemsで分割して処理する方法

ここでは外部サービスへ送信しない架空の5itemsを使い、Batch Sizeを2にしたときの「2・2・1件」を説明します。公式文書の確認日は2026年10月31日で、対象はBatch Size、Reset、loop／done出力を持つLoop Over Itemsの構成です。

例は公開仕様に基づく検証手順であり、実環境での成功記録ではありません。手元のn8n本体版、Loop Over Itemsのノード版、ワークフローの実行順設定を記録してから始めてください。

通常のitem処理で足りるか判断する

「データが複数あるからLoopを置く」という順で考える必要はありません。先に、後続ノードが何を1単位として処理するかを調べます。

自動反復・配列展開・Limitを分ける

n8nのitemは、ノード間で受け渡す1件分のデータです。たとえばIDがA〜Eの5itemsなら、多くのノードは設定した処理を各itemへ適用します。

一方、1itemの中にordersという配列があり、その配列に5要素が入っている状態は、外側の5itemsとは別です。配列要素を1件ずつ後続へ渡したいなら、先にSplit Outなどでitemsへ展開する方法を選んでください。

Limitは上限を超えたitemsを除くノードなので、全件処理を2件ずつ進める目的には合いません。入力が「5items」なのか「1item内の5要素」なのかを最初に確かめるだけでも、選択は整理できます。

ただし、自動で各itemを処理するかはノードと操作次第です。ノードのSettingsにあるExecute Onceが有効だと最初のitemだけを処理するため、期待と違う件数になったときはこの設定も確認してください。

CodeノードのRun Once for All Itemsは、渡されたitemsをコード側で扱うモードです。配列を返すだけなのか、件数を減らすのか、全件を加工するのかは書いたコードによって変わります。

配列の展開とCodeのモード選びを先に整理し、「何件ずつ処理を進めるか」の制御が必要な場合にLoopを選んでください。

loop側を戻し、done側で完了を扱う

既知の有限リストでは、Resetを無効にし、loop側の処理からLoop Over Itemsの入力へ戻すのが基本です。loopは次のバッチを渡す側、doneはすべてのバッチ処理が終わった後の結果を受け取る側として使います。

5件を2・2・1件に分ける

最初の検証では、認証情報や有料APIを使わない手動実行用ワークフローを作ってください。加工内容はIDを残してprocessed: trueを追加するだけです。

1. Manual Triggerと架空の5itemsを用意する

   Manual Triggerの後ろにCodeノードを置き、JavaScriptのRun Once for All Itemsを選びます。下のコードは、IDがA〜Eの入力を作るためのものです。

2. Loop Over Itemsの分割単位を指定する

   Codeの出力をLoop Over Itemsの入力へ接続し、Batch Sizeを2に設定してください。Resetは無効のままにします。

3. loop側でIDを保ったまま加工する

   loop出力をEdit Fields（Set）へつなぎ、Boolean型のprocessedへtrueを設定する構成です。入力のidが残るように、出力へ含める入力フィールドの設定も確かめてください。

4. 加工後をLoop Over Itemsへ戻す

   Edit Fieldsの出力から、同じLoop Over Itemsの入力へ接続を戻します。最初のバッチが加工されて戻ると、次のバッチへ進める形です。

5. done側を照合先として確認する

   手動でワークフロー全体を実行し、Loop Over Itemsの各実行とdone出力を見てください。完了後の通知や集計を追加するならdone側が候補ですが、最初は外部処理をつながず結果の確認だけにします。

入力作成用Codeのコードは次のとおりです。

return ['A', 'B', 'C', 'D', 'E'].map(id => ({  json: { id }}));

このコードをLoop内へ置くと、毎回A〜Eを作り直す別の処理になってしまいます。配置はManual Triggerの直後、Loop Over Itemsへ初めて入る前です。

出力ポートは上下の位置で覚えず、loopとdoneの名称を読んで接続してください。画面配置やノード版が異なっていても、どちらをバッチ処理へ使うかという判断は同じです。

doneで照合するのは、loop側で加工して戻したデータです。元の5itemsを無条件にそのまま再出力するという意味ではないため、idを残す設定とprocessedの両方を確認してください。

表では、この入力と1対1加工に対する期待値を並べています。入力を5件にしても、途中でFilterや集約を入れた構成では出力件数の条件は同じではありません。

戻り線がなければ、最初のバッチを処理しただけで次へ進まない状態になり得ます。反対に、done側へ1件ずつの加工を置いても、バッチ内の処理にはなりません。

件数とIDの両方で完了を判定する

doneへ到達したことだけで、目的どおり全件を処理できたとは決めないでください。Aが2回、B・C・Dが1回ずつなら合計は5件でも、Eが欠けた結果です。

この例では、次の3条件をそろえて完了と扱います。

• 入力IDのA・B・C・D・Eが、done出力へ各1回ずつ残っている。
• 各IDのprocessedがBoolean型のtrueになっている。
• 同じ実行の履歴で2・2・1件の処理と、その後のdone出力を確認できる。

検証時は「入力ID」「バッチ番号」「加工結果」「done側のID」を同じ実行にひも付けて記録してください。以前の実行結果が画面に残っていても、今回の完了証拠にはなりません。

途中で1件を複数件へ分割する、不要なitemsを除く、複数件を集約するといった設計では、入力件数とdone件数が一致しないこともあります。その場合は入力IDごとの処理結果や除外理由を含む別の期待表が必要です。

0itemsでは後続が動かない場合があるため、doneから必ず通知できるという前提で組まないでください。0件も記録する必要があるなら、入力を作る段階で0件の状態を別に検出する設計が必要です。

また、処理の継続だけを目的にダミーitemを本データへ無条件に混ぜる方法は避けます。専用のstatusを使う設計でも、通常データとして送信されない行き先と条件を決めてください。

Loopのdoneが集めるのは、全バッチの処理を終えて戻されたデータです。別々の入力をIDで照合して結び付けたい場合はMergeの役割になるため、バッチ処理の完了とキー結合を分けて考えてください。

待機と再試行を接続先の制限に合わせる

Batch Sizeは1回に渡すitem数の指定であり、APIの上限を自動で守る設定ではありません。送信間隔を空けたいときは、処理ノードの後ろへWaitを置き、WaitからLoop Over Itemsへ戻す構成を検討します。

Waitを戻り経路へ置く

基本例に待機を足すなら、loop出力からEdit Fields、Wait、Loop Over Itemsの入力へと接続する順です。外部処理のない例で待機単位を確かめてから、実際のAPIを使うノードへ置き換えてください。

Batch Sizeが2で、そのバッチ内のノードが2itemsへ各1リクエストを送る場合、Waitへ着く前に2回の要求が発生し得ます。1リクエストごとに間隔を空ける必要があるサービスなら、Batch Sizeを1にする方が確認しやすい構成です。

ただし、必要な待機秒数は接続先のAPI文書を読んで決めるもので、全サービス共通の正解はありません。少なくとも次の条件を外部処理の前に整理してください。

• 上限が秒・分・日などのどの単位で決まるか。
• リクエスト数以外に、同時実行数や処理量の上限があるか。
• 複数のワークフローや利用者で同じ枠を共有するか。
• 429の応答やRetry-Afterが返ったとき、どう待って再開するか。
• 再実行時に同じIDの書き込みが重複しないか。

公式文書では、Retry On Failによる再試行間隔の調整も案内しています。これは失敗後にもう一度要求する仕組みであり、通常時のバッチ間待機とは役割が別です。

途中で止まった後は、成功したIDと未処理IDを照合して再開対象を絞るのが安全です。単に最初から繰り返すと、すでに送った対象も再び処理することになります。

HTTP Request自体のBatchingで間隔を制御できる用途もあるため、待機のためだけにLoopを追加する前にノードの標準設定を比べてください。いずれを選んでも、接続先の上限と実行結果の照合が必要な点は同じです。

Resetを使う反復と停止条件を分ける

既知の5itemsを順番に処理する例では、Resetを有効にしません。Resetは現在の入力を新しいデータとして初期化する機能なので、同じitemsを戻すと同じ対象を繰り返す原因になります。

有限バッチに不要なResetを入れない

有限リストは、保存した入力をバッチに分け終わるまで進める設計です。通常の完了のために、追加のIF停止判定を必ず置く必要はありません。

これに対し、取得を始める時点ではページ数が分からないAPIでは、次の入力を読み直しながら反復する別の設計が必要になります。Resetを使う例があるのは、このように毎回の入力を新しいデータ集合として扱いたい場合です。

ページ取得では、接続先が示す終端条件に加え、少なくとも「next_cursorがあるか」「同じcursorが再登場していないか」「最大ページ数を超えていないか」を整理してください。ここで挙げた条件は、汎用の設計上のチェックです。実際のパラメータ名や終端条件は接続先のAPI文書に従います。

たとえば空ページでも次のcursorを返すAPIなら、空だったという理由だけでは終了と決められません。終端条件はそのサービスの仕様に合わせ、同じcursorの再登場や上限超過は異常として停止させます。

反復が止まらない試験は、まず実行を停止してください。その後、手動トリガーだけの検証用構成に保ち、戻り先・Reset・同じ入力の再生成・停止判定の順に原因を絞ります。

外部サービスへすでに送った処理は、n8n側の停止だけで巻き戻せるとは限りません。再開前に処理済みIDを確かめ、重複させない対象だけを改めて流す判断が必要です。

条件式や保持する分岐先はIF・Switch・Filterで設定します。本稿の5items例で入力と戻り先が正しいことを確認してから、必要な条件を一つずつ追加してください。

まとめ｜必要な分割と待機を決め、全IDの処理完了を確かめる

Loop Over Itemsは、複数データがあるときに必ず足すノードではありません。通常のitem処理で足りるかを先に見極め、分割単位やバッチ間の待機を制御したい場合に使います。

既知の有限リストではBatch Size、Reset無効、loop側からの戻り先、done側での照合が基本です。まずは架空のA〜Eを2・2・1件に分ける例を手動実行し、全IDが各1回、処理結果とともに残るかを確認してください。

反復回数だけを見るより、どのIDを処理したかを残す方が、欠落の発見と途中停止後の再開判断に役立ちます。待機秒数を調整する前に処理対象と完了条件をそろえることが、無理なく反復を管理する出発点です。

参考資料（公式文書を2026年10月31日に確認。公開文書の仕様と利用中のノード版は別途照合）

• n8n公式：Loop Over Items
• n8n公式文書：Looping in n8n
• n8n公式文書：Handle rate limits
• n8n公式文書：Limit
• n8n公式文書：Edit Fields（Set）