# list

### Overview

The `list` RPC method retrieves metadata for files stored on the Lynx blockchain by the authenticated tenant. This command provides a comprehensive view of all your stored files, arranged chronologically with the most recently stored files appearing first in the results.

### Syntax

```
list [count]
```

### Description

When you invoke the `list` method, the Lynx daemon scans the blockchain for files associated with your tenant account and retrieves metadata about each file. This includes the unique identifier, file size, storage location, and timestamp information. This command is essential for managing your blockchain-stored files and serves as a directory service for your decentralized storage.

### Parameters

<table><thead><tr><th>Parameter</th><th width="142">Type</th><th width="106">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>count</code></td><td>string/integer</td><td>No</td><td>The maximum number of file records to retrieve. If omitted, the default is 10 records. To retrieve more files, you can specify a high number or 0 for all files.</td></tr></tbody></table>

### Returns

The method returns a nested array structure containing file metadata:

```
[
  [
    {
      "uuid": "00112233445566778899aabbccddeeff",
      "length": 12345,
      "height": 987654,
      "timestamp": "2023-05-15 14:30:22"
    },
    {
      "uuid": "aabbccddeeff00112233445566778899",
      "length": 54321,
      "height": 987650,
      "timestamp": "2023-05-14 09:15:37"
    },
    ...
  ]
]
```

Each file entry contains the following fields:

| Field       | Type   | Description                                                                                                                                                |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`      | string | The unique identifier of the file. This is a 32-character hexadecimal string that serves as the primary reference for the file in the Lynx storage system. |
| `length`    | number | The total size of the file in bytes. This represents the complete file size, even if the file data is distributed across multiple blockchain blocks.       |
| `height`    | number | The starting block number where the file storage began. Files may span multiple blocks depending on their size.                                            |
| `timestamp` | string | The date and time when the file storage operation was initiated, in `YYYY-MM-DD HH:MM:SS` format.                                                          |

### Authentication Requirements

The `list` method requires user authentication:

* You must authenticate using the appropriate credentials before using this command
* If not authenticated, the method will return a simple "Not authenticated" message
* The method only retrieves files associated with the authenticated tenant

### Performance Considerations

* The `list` command scans the blockchain to find files, which can be resource-intensive
* For large storage histories, limiting the results with the `count` parameter can improve performance
* The command logs the execution time to the debug log, which can be useful for monitoring performance
* The default limit of 10 recent files helps optimize performance for routine usage

### Examples

#### List the 10 most recently stored files (default)

```
lynx-cli list
```

Or using JSON-RPC:

```
curl --user username --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "list", "params": []}' -H 'content-type: text/plain;' http://127.0.0.1:9332/
```

#### List the 5 most recently stored files

```
lynx-cli list 5
```

#### List all stored files

```
lynx-cli list 0
```

### Implementation Notes

* Only files with complete metadata (file length > 0) are included in the results
* The command measures and logs its execution time for performance monitoring
* The results are presented with the most recent files first (chronological order, newest to oldest)