n8n-loops

n8n のループ

「ループ」には3つの意味があり、それぞれ異なる仕組みに対応します。

1. 「このノードを各アイテムに対して実行する。」 デフォルトです。ほとんどのノードは自動でループするため、何もする必要はありません。
2. 「各アイテムに対してではなく、すべてのアイテムをまとめてこのノードを 1回 実行する。」 executeOnce 設定（単一のブール値）を使います。
3. 「イテレーション間の制御フローを含め、アイテムを明示的なバッチで処理する。」 Loop Over Items ノード（旧称 Split In Batches）を使います。

ページネーションのある API では、HTTP Request ノードにページネーション機能が組み込まれています。手作業でページ数を数えるループを構築するより、ほぼ常にこちらが適しています。

モデル：アイテムは配列です

データはノード間をアイテムの配列として流れます。各アイテムは { json: {...}, binary?: {...} } です。50個のアイテムは、50件の要素を持つ配列です。

デフォルトでは、ノードはアイテムごとに1回実行されます。入力アイテムが50個ある HTTP Request は、50件のリクエストを送信し、結果のアイテムを50個出力します。これは、ほとんどのワークフローが利用している暗黙のループです。

入力配列がループです。 配列を制御してイテレーションを制御します。

必須事項

ノードをアイテムごとではなく、実行ごとに1回だけ実行する場合は、必ず executeOnce: true にします。これには、$input.all()／$('Node').all() と .map()／.filter()／.reduce() を使ってデータセット全体を集計する式も含まれます（これを設定しないと、集計が上流のアイテム数 N 回計算され、下流で同じ結果が N 個生成されることがよくあります）。単一の通知、集計結果の書き込み、要約メッセージも対象です。

例外： .all() を別のノードの .item（アイテムごとの参照。例：$('Get Tags').all().filter(tag => $('Search Posts').item.json.tag_ids.includes(tag.json.id))）と組み合わせる処理は、実際のアイテムごとの処理なので、executeOnce はオフのままにします。詳しい違いについては、n8n-expressions スキルの executeOnce セクションを参照してください。

基本方針

• デフォルトのイテレーションで十分なら、ループを構築しないでください。 ほとんどのノード（HTTP Request、ネイティブサービスノード、Set、IF／Switch）は、入力アイテムごとに自動で1回実行されます。入力が N 個なら、実行も N 回です。HTTP リクエストを N 回送信したり、レコードを N 件作成したりするには、ソースをノードに接続するだけです。イテレーションごとの制御が必要な場合を除き、Loop Over Items は使わないでください。（注：Execute Workflow は例外です。デフォルトでは、すべてのアイテムを1つのバッチにまとめます。mode: 'each' については n8n-subworkflows を参照してください。）
• ページネーションのある API では、HTTP Request の組み込みページネーションを使ってください。 API に特異な点がある場合を除き、Loop Over Items と手動の $pageCount を組み合わせて独自に実装しないでください。references/HTTP_PAGINATION.md を参照してください。
• Loop Over Items は、明示的なバッチ処理やイテレーションごとの制御（レート制限、バッチごとのエラー回復、状態を保持するチャンク、ポーリング）に使います。references/LOOP_OVER_ITEMS.md を参照してください。
• アイテムごとのイテレーションは逐次処理であり、並列処理ではありません。 並列に見えるブランチでも、次のアイテムが開始する前に各アイテムの処理が完了します。実際の並行処理パターンについては、n8n-subworkflows を参照してください。

判断ツリー：どの仕組みを使えばよいですか？

Need to do something for each item?
├── Default per-item iteration is enough
│   └── Just connect the node. Done.
│
├── The node should run once total, not once per item?
│   └── Set executeOnce: true on the node
│
├── Paginated API (multiple HTTP calls to fetch all pages)?
│   └── Use HTTP Request's Pagination option (see references/HTTP_PAGINATION.md)
│
├── Need explicit batching (rate limit, chunk size, per-batch error handling)?
│   └── Use Loop Over Items node (see references/LOOP_OVER_ITEMS.md)
│
└── Need to recurse / repeat with state until a condition is met?
    └── Loop Over Items with Reset, OR a sub-workflow that calls itself.
        Both are advanced patterns; see references/LOOP_OVER_ITEMS.md.

executeOnce：1回だけ実行する設定

すべてのノードの Settings タブに Execute Once トグルがあります。オンにすると、最初の入力アイテムのみを使ってノードが1回実行されます。SDK コードでは、次のように executeOnce: true を設定します。既存のワークフローでは、update_workflow の setNodeSettings を使って適用します（n8n 2.24.0+）。

{
    name: 'Aggregate Slack',
    type: 'n8n-nodes-base.slack',
    parameters: { /* ... */ },
    executeOnce: true,
}

使用する場面：

• 通知と集計結果の書き込み。 100個のアイテムが入力されたからといって、「要約メッセージ」が100回送信されるべきではありません。
• カウンター、合計、レポート。 $input.all().length などを計算するものは、すべて1回だけ実行するべきです。
• $input.all()／$('Node').all() を使って配列全体を集計する式。 そうしないと、集計が上流のアイテムごとに実行されます。（別のノードの .item で絞り込む .all() を使ったアイテムごとの 参照 は例外です。n8n-expressions を参照してください。）

使用しない場面：

• アイテムごとの処理。 アイテム ごと に1回通知するのはデフォルトの動作で、通常はそれが正しいです。
• アイテムごとに分岐する HTTP リクエスト。 アイテムごとに1回ずつリクエストを送信する必要があります。

最もよくある間違いは、集計ノードに executeOnce を設定し忘れ、分岐後に同じメッセージが50回送信されることです。

暗黙のループが問題を起こすとき

項目ごとのデフォルトの反復処理は、必要になるまでは便利です。よくある意外な動作を紹介します。

「単一」の設定ノードが項目ごとに実行される

ファンアウトの後にある Set ノードは項目ごとに一度実行され、同じ定数を N 個生成します。通常は問題ありませんが、コストの高い式（長い JSON.stringify や Luxon の解析）は N 回実行されます。Set をファンアウトの前に移動するか、executeOnce: true を設定してください。

集約用の Code ノードが N 回実行される

$input.all() を読み取って合計を計算する Code ノードは、executeOnce: true がないと上流の項目ごとに一度実行され、同一の項目を N 個生成します。executeOnce: true を設定してください。

Webhook 応答ノードが 2 回実行される

最も厄介なケースです。Respond-to-Webhook は入力項目ごとに実行され、2 つのブランチがマージノードなしで合流すると 2 回実行されます。最初の応答が採用され、残りはエラーとして記録されます。まずマージするか、応答ノードに到達するブランチが 1 つだけになるようにしてください。n8n-node-configuration の references/MERGE_NODE.md を参照してください。

1 つの要約が必要なのに、LLM 呼び出しが N 回実行される

集約用 Code ノードと同じパターンです。プロンプト内で $input.all() を使う LLM ノードは、executeOnce: true がないと同一の呼び出しを N 回実行し、N 回分のトークンを消費して、同一の回答を N 個返します。

Loop Over Items を使う場面

デフォルトの反復処理でほとんどのケースに対応できます。次のような場合は Loop Over Items を使います。

• レート制限。「一度に 10 件処理し、バッチ間で 1 秒待つ。」
• 配列のリクエストボディを使ったバッチ API 呼び出し。「50 件ずつに分けて /bulk に送信する。」
• バッチごとのエラー処理。「バッチが失敗したら、記録して続行する。」
• 状態を持つ反復処理。「各反復処理が前回の出力に依存する。」
• 長時間実行されるジョブのポーリング。「開始後、完了するか上限に達するまで 30 秒ごとにステータスを確認する。」reset: true と $runIndex の上限値を使用します。
• 集約を伴う項目ごとのマルチブランチ処理。「入力ごとに変換処理を並列実行し、マージしてから集約する。」完了出力（インデックス 0）に結果が含まれます。

配線の詳細、出力インデックスに関する注意点（出力 0 = 完了、出力 1 = ループ）、および具体例については、references/LOOP_OVER_ITEMS.md を参照してください。

Loop Over Items を使わない場面

最もよくある誤った判断は、「次のステップに進む前にすべての項目の処理が終わるまで待つ必要があるので、Loop Over Items を追加して done 出力を使おう」です。**そのために Loop Over Items を使う必要はありません。**デフォルトの項目ごとの反復処理ではすでに待機します。各項目は次の項目の処理が始まる前に下流チェーン全体を通過し、ループ後のノードが「早く」実行されることはありません。

この誤りを直す方法は、ほとんどの場合、Loop Over Items ノードを削除し、ほかは何も変えずにリリースすることです。これが以下のシナリオ 1 で、大半のケースに当てはまります。

4 つのシナリオはそれぞれ独立しています。すべてが Loop Over Items の「代替」だと捉えるのではなく、個別の判断として読んでください。ほとんどの構築ではシナリオ 1 だけで完了します。シナリオ 2 と 3 は、それぞれ固有の目的がある場合にのみ検討します。シナリオ 4 は、Loop Over Items を使う意味がある限定的なケースです。

シナリオ 1：項目ごとのデフォルトの反復処理（デフォルトで最も一般的）

ソースが N 個の項目を出力し、項目ごとの処理ノードが N 回実行され、その後に下流チェーンが続きます。**Loop Over Items も executeOnce も Aggregate も不要です。**ノードを接続するだけです。

[Source: 20 items]
  → [Per-item processor]   # default iter, runs 20 times
  → [Next step]            # runs after each item, in order

「すべての項目を待つため」や「次のノードを項目ごとに実行するため」に Loop Over Items + done を追加した場合は、Loop Over Items ノードを削除し、ソースから処理ノードへ直接配線してください。**ほかのものに置き換える必要はありません。**デフォルトの反復処理で十分です。例外は Execute Workflow（サブワークフロー）です。デフォルトでは全項目を 1 つのバッチとして処理するため、項目ごとに呼び出すにはループではなく、そのノードに mode: 'each' を設定します。n8n-subworkflows を参照してください。

シナリオ 2：後続ノードを合計 1 回だけ実行する（executeOnce: true）

シナリオ 1 とは独立しています。1 アイテムごとではなく、1 回の実行につき 1 回だけ処理する特定の後続ノードがある場合に限ります。たとえば、20 件の論文を処理した後に送るダイジェストメール、ループ後に 1 回だけ書き込むサマリー、最後に送る Slack 通知です。

そのノードに executeOnce: true を設定します。ノードは上流のすべてのアイテムを受け取りますが、実行は 1 回だけです。これはノードごとの設定であり、Loop の代替ではありません。シナリオ 1 のアイテムごとの処理ノードは引き続き N 回実行され、この後続ノードだけが 1 回に集約されます。

シナリオ 3：ノードがアイテムを単一の配列として必要とする（Aggregate）

シナリオ 1 とは独立しています。後続ノードの入力仕様が、アイテムごとの呼び出しではなくリストである場合に限ります（例：JSON 配列のボディを受け取るノード、リスト全体を必要とする LLM プロンプト）。

Aggregate ノードを使って、アイテムごとのストリームを、配列を含む 1 つのアイテムに集約します。これも Loop の代替ではありません。

シナリオ 4：本当のバッチ処理（Loop Over Items が役立つ唯一のケース）

レート制限（N 件ずつ処理し、バッチ間に Wait を挟む）、分割した一括 API 呼び出し（50 件の配列を /bulk に POST する）、バッチごとのエラー処理、reset: true と $runIndex の上限による実行時間の長いジョブのポーリング、各バッチが前回の出力に依存するステートフルな反復処理。

「アイテムの完了を待つ」だけでは該当しません。デフォルトの反復処理ですでに実現できます。

すぐに判断するには

Loop を使う理由が「アイテムを待つ／各アイテムで実行する」だけなら、シナリオ 1 に該当します。Loop を削除してください。代わりに executeOnce や Aggregate を追加しないでください。これらは別の問題を解決するもので、それぞれのシナリオに該当する場合にのみ追加します。

HTTP ページネーションを使うべき場合

よくあるページ形式は次の 3 種類です。

• レスポンス内の次ページ URL。 各レスポンスに next リンクが含まれます。
• ページ番号／カーソルのパラメーター。 呼び出しごとに ?page=N または ?cursor=... を増やします。
• 空のページまたは特定のステータスで停止します。

HTTP Request は Pagination オプションで、これらすべてに標準で対応しています。モードを設定し、次ページの式を指定すると、ノードが内部でループし、すべてのページのアイテムを含む単一の出力配列を返します。

API が組み込みモードでは表現できない処理を必要としない限り、Loop Over Items と手動の $pageCount で作り直す必要はありません。

references/HTTP_PAGINATION.md を参照してください。

サブワークフローの再帰

本当に再帰的な処理（ツリーの走査、バックオフ付きの再試行、「これとその子を処理する」など）には、Reset を使った Loop Over Items よりも、自己呼び出しするサブワークフローのほうがシンプルです。入力パラメーターで再帰の状態を受け渡します。

Sub-workflow: Walk Tree
  inputs: { node_id, depth }
  body: process node, look up children, for each child call self with depth+1

再帰の深さに注意してください。n8n にはネストされた実行の上限があります。深い再帰では、真の再帰よりもキューとフラットなループを使うほうが適しています。

参照ファイル

ファイル	読むタイミング
references/LOOP_OVER_ITEMS.md	Loop Over Items ノードの設定、バッチ処理、レート制限、ステートフルな反復処理を行う場合
references/HTTP_PAGINATION.md	ページネーションに対応した API の呼び出し、HTTP Request のページネーションモードの設定を行う場合

アンチパターン

アンチパターン	問題点	修正方法
デフォルトの反復処理ですでに実行されるのに、「ループさせるため」に Loop Over Items を追加する	メリットがないのにワークフローが読みにくくなり、ループ出力と完了出力の接続を誤りやすくなります	ノードを直接接続し、デフォルトの反復処理に任せます
executeOnce を設定していない Aggregate Code ノード	集約処理が N 回実行され、同じ項目が N 個出力されます	executeOnce: true を設定します
Loop Over Items と $pageCount を使った手動ページネーションループ	HTTP Request が標準で行う処理を独自に実装することになり、停止条件も壊れやすくなります	HTTP Request の Pagination オプションを使います
要約を送りたいのに、項目ごとに Slack メッセージを送る	Slack チャンネルがメッセージであふれ、レート制限に達し、気まずいことになります	Slack ノードに executeOnce: true を設定し、上流で要約を作成します
2 つのブランチがどちらも Respond to Webhook に到達する	2 回応答され、呼び出し元でエラーが発生します	応答ノードの前でマージするか、そこに到達するブランチが 1 つだけになるようにします
Reset を設定した Loop Over Items に明確な終了条件がない	無限ループになり、実行が強制終了されるまで n8n がメモリを消費します	必ず明確な終了条件を設けます。ページネーションに対応した API では、HTTP のページネーションを優先してください
同じワークフロー内で Loop Over Items を別の Loop Over Items の中にネストする	検証には通りますが、実行時に壊れます	内側のループをサブワークフローに移し、外側の反復ごとに呼び出します。n8n-subworkflows の mode: 'each' を参照してください