List Files Node

List files in a Needle collection with pagination support.

The List Files node retrieves a list of files from a Needle collection. It supports pagination through an offset parameter, making it suitable for processing large collections in batches — typically inside a loop node.

Parameters

Parameter	Type	Required	Default	Description
collectionId	string	✅		The Needle collection to list files from
offset	string	✅	"0"	Number of files to skip from the start (supports expressions)
instructions	string	❌	""	Additional instructions (template mode)
runMode	string	✅	item	Run mode: item or input

collectionId

Type: string | Required: ✅

The ID of the Needle collection. Select from the dropdown in the node configuration UI.

offset

Type: string | Required: ✅ | Default: "0"

The number of files to skip. Use this for pagination — for example, set to "0" for the first page, "20" for the second page, etc. Supports expressions for dynamic pagination inside loops.

Examples:

• Static: "0" (start from the beginning)
• Dynamic (expression): input.loop.index * 20 (paginate through files in a loop)

instructions

Type: string | Required: ❌

Additional natural language instructions for listing behavior. Evaluated in template mode.

runMode

Type: string | Required: ✅ | Default: item

Controls how the node processes input data:

• item — Runs once per array element.
• input — Runs once for the entire input.

Configuring This Node

When you click the List Files node in the workflow builder, a configuration panel appears with the following sections from top to bottom:

Run Mode & Continue on Error

At the top of the panel is a Run Mode dropdown with two options:

• Item — The node executes once for every element in the input array. Use item in expressions to reference the current element.
• Input — The node executes once for the entire input. Use input in expressions to reference the full input.

Next to the dropdown is a Continue on Error toggle. When enabled, the workflow continues executing downstream nodes even if this node fails. The error is captured in the node's output so downstream nodes can inspect and handle it.

Variables

A multi-select dropdown that lets you bind workflow-level variables to this node. Variables are defined at the workflow level and can hold string, number, boolean, or secret values. Once selected, the variables become available in expressions via the variables object (e.g., variables.pageSize). You can also click the Create variable button to define a new variable without leaving the node configuration panel.

Collection

A dropdown that lists all Needle collections available to you. Select the collection whose files you want to list. The selected collection's ID is used as the collectionId parameter.

Instructions

A template text area for optional AI instructions. Supports ${...} template literal syntax for inserting dynamic values. These instructions guide the AI agent in how to use the tool when the node is part of an AI-driven workflow.

Property Fields

The remaining parameters (offset) are displayed as property fields, organized into Required and Optional sections based on the node's schema. Each field has a mode toggle that lets you switch between three parameter modes:

• Fixed — Enter a static value directly in the field.
• Expression — Write a JavaScript expression that is evaluated at runtime. Expressions can reference input, item, variables, and other context objects.
• AI Decide — Let the AI agent determine the value based on the surrounding context and instructions.

Examples

1. List All Files (First Page)

Retrieve the first batch of files from a collection:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "offset": "0"
}

2. Paginate Through Files in a Loop

Use inside a loop node to process all files in batches of 20:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "offset": "input.loop.index * 20",
  "parameterMode": {
    "offset": "expression"
  }
}

3. List Files with Instructions

Provide additional context for the listing:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "offset": "0",
  "instructions": "List files from the collection. You can adjust the offset and limit to control which files to process."
}

Output Structure

The node returns an array of file objects:

[
  {
    "id": "fle_01ABC...",
    "name": "quarterly-report.pdf",
    "type": "application/pdf",
    "size": 245000,
    "status": "indexed",
    "createdAt": "2025-03-01T10:00:00Z"
  },
  {
    "id": "fle_02DEF...",
    "name": "meeting-notes.docx",
    "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "size": 18200,
    "status": "indexed",
    "createdAt": "2025-03-02T14:30:00Z"
  }
]

Important Notes

• Pagination: Files are returned in batches (typically 20 per page). Use the offset parameter with a loop node to iterate through all files.
• Collection access: The user running the workflow must have at least viewer access to the collection.
• Combining with Get File Contents: Use List Files to get file IDs, then Get File Contents to retrieve the actual content of specific files.
• Continue on Error: Use the toggle at the top of the configuration panel to allow the workflow to continue even if this node fails. The error details are captured in the node's output for downstream handling.
• Workflow Variables: You can bind workflow-level variables (string, number, boolean, or secret) to this node using the Variables multi-select. Selected variables are accessible in expressions via the variables object.
• Parameter modes: Each property field can be switched between Fixed (static value), Expression (runtime JavaScript expression), and AI Decide (let the AI agent choose the value) modes using the toggle on the field.