> For the complete documentation index, see [llms.txt](https://docs.datajet-app.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datajet-app.com/liquid/tags/ftp_list.md).

# ftp\_list

Lists files and directories at a specified path on the FTP/SFTP server. Must be used inside an `ftp_session` block.

```liquid
{% ftp_session host: "ftp.example.com", user: "myuser", password: "mypass" %}
  {% ftp_list path: "/data" as result %}

  {% if result.ok %}
    {% for file in result.files %}
      {% log file.name %}
    {% endfor %}
  {% endif %}
{% endftp_session %}
```

#### Syntax

```liquid
{% ftp_list path: "/directory/path" as result_variable %}
```

#### Parameters

| Parameter | Required | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `path`    | Yes      | Directory path to list                         |
| `pattern` | No       | Glob pattern to filter files (e.g., `"*.csv"`) |

#### Result Object

| Property | Type        | Description                                         |
| -------- | ----------- | --------------------------------------------------- |
| `ok`     | boolean     | `true` if listing succeeded                         |
| `error`  | string/null | Error message if `ok` is `false`, `null` on success |
| `files`  | array       | Array of file objects                               |

Example result:

```json
{
  "ok": true,
  "error": null,
  "files": [
    {
      "name": "data.csv",
      "type": "file",
      "size": 1024,
      "path": "/exports/data.csv",
      "modifiedAt": 1704067200
    }
  ]
}
```

#### File Object Properties

| Property     | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `name`       | string | File or directory name              |
| `path`       | string | Full path to the file               |
| `type`       | string | `"file"` or `"dir"`                 |
| `size`       | number | File size in bytes                  |
| `modifiedAt` | number | Unix timestamp of last modification |

#### Examples

**List all files:**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/exports" as result %}

  {% if result.ok %}
    {% log "Found files:" %}
    {% for file in result.files %}
      {% log file.name %}
    {% endfor %}
  {% else %}
    {% log result.error %}
  {% endif %}
{% endftp_session %}
```

**Filter by pattern:**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/data", pattern: "*.csv" as csv_files %}

  {% for file in csv_files.files %}
    {% log file.name %}
  {% endfor %}
{% endftp_session %}
```

**Filter files only (exclude directories):**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/uploads" as result %}

  {% for item in result.files %}
    {% if item.type == "file" %}
      {% log item.name %}
    {% endif %}
  {% endfor %}
{% endftp_session %}
```

**Sort by modification date:**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/logs" as result %}

  {% assign sorted_files = result.files | sort: "modifiedAt" | reverse %}
  {% assign latest_file = sorted_files | first %}
  {% log latest_file.name %}
{% endftp_session %}
```

#### Notes

* Must be used inside an `ftp_session` block
* Consumes 2 credits per operation
* Pattern uses glob syntax (e.g., `*.csv`, `report_*.txt`, `**/*.json`)
* Returns empty `files` array if directory is empty


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.datajet-app.com/liquid/tags/ftp_list.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.