> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Files

> List raw file objects in document storage for a namespace using the Python SDK

## documents.list\_files

Lists file objects stored under your namespace prefix in document storage (S3): `file_name`, `size` (bytes), and `last_modified`. This is **not** the same as indexed text documents; use `documents.get` or `documents.fetch_text_data` for pipeline output.

### Parameters

<ParamField query="namespace_name" type="str" required>
  The name of the target namespace (must exist and belong to your account).
</ParamField>

**Returns:** `Dict[str, Any]` - A dictionary with listing results.

Common response fields include `success`, `namespace`, `file_count`, and `files` (each item: `file_name`, `size`, `last_modified`). Keys are **snake\_case** after SDK normalization.

**Raises:** `NamespaceNotFound`, `InvalidInputError`, `AuthenticationError`, `APIError`, `MoorchehError`.

### Example

```python List Files Example theme={null}
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    status = client.documents.list_files(namespace_name="my-faq-documents")
    print(status)
```

### Async Example

```python List Files Async Example theme={null}
import asyncio
from moorcheh_sdk import AsyncMoorchehClient

async def main():
    async with AsyncMoorchehClient() as client:
        status = await client.documents.list_files(namespace_name="my-faq-documents")
        print(status.get("file_count"), status.get("files"))

asyncio.run(main())
```

### Complete Example

```python Complete List Files Workflow theme={null}
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    listing = client.documents.list_files(namespace_name="my-data")
    print(f"Namespace: {listing.get('namespace')}")
    print(f"File count: {listing.get('file_count')}")
    for f in listing.get("files", []):
        print(f["file_name"], f["size"], f.get("last_modified"))
```

## Important Notes

<Note>
  **Raw storage listing**: Each entry in `files` describes an object in storage (for example after `documents.upload_file`), not a text document row from the indexing pipeline alone.
</Note>

<Note>
  **Ordering**: Do not assume a stable sort from the API; sort client-side if you need a specific order.
</Note>

<Warning>
  **API usage**: Each successful call counts toward your plan like other authenticated API requests.
</Warning>

## Best Practices

* Use listing for audits, cleanup, or UI file pickers; use search for semantic queries over processed content
* Sort or filter client-side when you need deterministic ordering
* Use [Delete Files](/python-sdk/files/delete-files) (`documents.delete_files`) when you need to remove storage objects by file name

## Related Operations

* [Upload File](/python-sdk/files/upload-file) - Upload files via pre-signed flow
* [Delete Files](/python-sdk/files/delete-files) - Remove file objects by name from storage
* [Fetch Text Data](/python-sdk/data/fetch-text-data) - List ingested text and summary chunks
* [Search](/python-sdk/search/query) - Query uploaded and processed content
* [Delete Data](/python-sdk/data/delete) - Remove documents by ID