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


---

# 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.getlynx.io/lynx-core/data-storage/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.