# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.