n8n Loop Over Items: batching y bucles automáticos

n8n normalmente procesa varios registros completamente por sí solo: un node recibe una lista de items, ejecuta su lógica para cada item individual y devuelve los resultados de nuevo como una lista. Para la mayoría de los workflows, por tanto, no necesitas ningún bucle explícito. Pero en cuanto un servicio externo solo permite pocas solicitudes por segundo, un node procesa solo el primer item, o hay que consultar una API paginada sin un número de páginas conocido, el procesamiento automático ya no es suficiente. Precisamente para eso existe en n8n el node Loop Over Items, antes conocido como Split in Batches.

En este artículo te mostramos cómo funciona el bucle automático en n8n, cómo funciona en detalle el node Loop Over Items y en qué debes fijarte respecto al tamaño de batch y al rendimiento, para que tus workflows funcionen de forma estable y sin errores de límite de tasa.

Cómo recorre n8n los items automáticamente

Según la documentación oficial de n8n sobre bucles , los nodes de n8n aceptan en principio cualquier cantidad de items, los procesan y devuelven de nuevo los resultados. Si conectas, por ejemplo, un node de almacenamiento de datos con cinco registros de clientes a un node de Slack, n8n envía automáticamente cinco mensajes individuales, uno por registro. No necesitas construir tu propio bucle para esto, el motor se encarga de ello en segundo plano.

Si en cambio quieres procesar solo el primer item de un registro entrante, activas en la configuración del node, en la pestaña Settings, la opción Execute Once. Con esto el node ignora todos los demás items y procesa solo el primer registro, lo cual sirve por ejemplo para notificaciones puntuales.

El node Loop Over Items en detalle

Para todos los casos en los que el procesamiento automático no es suficiente, n8n aporta el node Loop Over Items . El node guarda los datos de entrada originales y devuelve en cada ejecución una cantidad fija de items a través de la salida loop . Cuando se han procesado todos los batches, combina los datos procesados y los devuelve a través de la salida done .

Dos ajustes son centrales aquí:

• Batch Size: determina cuántos items devuelve el node por ejecución. Si estableces el valor en 1, n8n procesa cada item individualmente, uno tras otro.
• Reset: reinicializa el node en cada ejecución con datos de entrada nuevos. Esto es útil para consultas de API paginadas en las que no conoces de antemano el número total de páginas. Importante según la documentación: si Reset está activado, debes incorporar sin falta una condición de parada válida, de lo contrario el bucle se ejecuta indefinidamente.

En la práctica, para esto utilizas expresiones como `{{$("Loop Over Items").context["noItemsLeft"]}}`, para comprobar si quedan items, o `{{$("Loop Over Items").context["currentRunIndex"]}}`, para leer el índice de la ejecución actual y usarlo como condición de parada en un node IF.

Cuándo debes hacer el bucle manualmente

Según la documentación, algunos nodes procesan por principio solo el primer item o todos los items a la vez, en lugar de iterar correctamente. Entre ellos se encuentran, entre otros, CrateDB, Microsoft SQL, MongoDB y TimescaleDB en operaciones de inserción y actualización, el node Code, así como el node Execute Workflow en modo "Run Once for All Items", el node HTTP Request en caso de paginación manual, la operación Redis Info y el node RSS Read. Para estas excepciones, construyes el bucle manualmente: conectas la salida de un node de nuevo a un node anterior y añades un node IF que comprueba una condición de parada clara.

Tamaño de batch y rendimiento en la práctica

El tamaño de batch determina directamente lo estable y lo rápido que se ejecuta un workflow. Un tamaño de batch pequeño, por ejemplo de 1 a 5 items por ejecución, protege a las APIs externas con límites de tasa estrictos, pero alarga el tiempo total de ejecución, porque n8n tiene que procesar más ejecuciones individuales. Un tamaño de batch grande acelera el workflow, pero aumenta el riesgo de que un servicio responda con un error 429 o de que el workflow sea más difícil de rastrear si se produce un error en medio de un batch grande. En la práctica, lo mejor es probar con un tamaño de batch moderado y observar los tiempos de ejecución, así como posibles respuestas de error del servicio de destino, antes de seguir aumentando el valor.

Especialmente en workflows de producción con muchas llamadas externas, merece la pena combinar Loop Over Items específicamente con tiempos de espera entre los batches, para que las APIs no se sobrecarguen y mantengas el control sobre la ejecución. Si quieres no solo construir tus workflows de n8n, sino también operarlos de forma estable a largo plazo, en NordFlux te apoyamos en el marco de nuestra automatización con n8n precisamente en estas cuestiones de rendimiento y límite de tasa, para que tus trabajadores digitales funcionen de forma fiable.

Preguntas frecuentes

¿Cuál es la diferencia entre el bucle automático y el node Loop Over Items?

El bucle automático ocurre por sí solo en casi todos los nodes de n8n: el node procesa cada item entrante individualmente y pasa la lista de resultados, sin que tengas que configurar nada para ello. El node Loop Over Items entra en juego solo cuando quieres dividir explícitamente el procesamiento en porciones controladas, por ejemplo para cumplir límites de tasa o para servir a nodes que solo pueden procesar un item a la vez.

¿Cómo evito un bucle infinito con el node Loop Over Items?

Un bucle infinito surge normalmente cuando la opción Reset está activada, pero no se comprueba ninguna condición de parada. En este caso, incorpora un node IF que evalúe, por ejemplo, la expresión `{{$("Loop Over Items").context["noItemsLeft"]}}`, y dirige el workflow a la rama done en lugar de volver al bucle una vez alcanzado el final.

¿Qué tamaño de batch debo elegir para las solicitudes de API?

No existe un número general, porque cada servicio tiene sus propios límites de tasa. Como punto de partida son adecuados valores pequeños entre 1 y 10 items por batch, que después ajustas progresivamente según los tiempos de respuesta reales y posibles mensajes de error del servicio de destino.

¿Tengo que construir yo mismo un bucle para cada node?

No, la mayoría de los nodes de n8n procesan varios items automáticamente sin configuración adicional. Solo para un número limitado de nodes de excepción, por ejemplo determinados nodes de base de datos o el node HTTP Request en caso de paginación manual, debes construir el bucle tú mismo con el node Loop Over Items o un node IF reconectado hacia atrás.

¿Puedo acceder dentro de un bucle a datos de ejecuciones anteriores?

Sí, a través de las propiedades context del node Loop Over Items, como currentRunIndex, puedes identificar la ejecución actual, y a través de referencias a nodes anteriores en el workflow también se pueden incorporar datos de pasos anteriores. Para un almacenamiento intermedio más complejo a lo largo de varias ejecuciones, se recomienda además un node Set o Code que recopile resultados intermedios.