> ## 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 indexed files and upload status for a text namespace.

## Overview

Returns all file records from the namespace file registry: paths, chunk counts, upload status, and custom metadata.

## Path parameters

<ParamField path="namespace_name" type="string" required>
  Text namespace to list.
</ParamField>

## Request example

```bash theme={null}
curl "http://localhost:8080/namespaces/my-documents/files"
```

## Response fields

<ResponseField name="status" type="string">
  `"success"` on success.
</ResponseField>

<ResponseField name="count" type="number">
  Number of file records.
</ResponseField>

<ResponseField name="files" type="array">
  File records sorted by filename.
</ResponseField>

<ResponseField name="files[].file_id" type="string">
  Server-generated file id (use for [delete by id](/on-prem/api-references/files/delete)).
</ResponseField>

<ResponseField name="files[].absolute_path" type="string">
  Container path used at upload (e.g. `/uploads/document.pdf`).
</ResponseField>

<ResponseField name="files[].filename" type="string">
  Basename of the file.
</ResponseField>

<ResponseField name="files[].file_type" type="string">
  File extension including the dot (e.g. `.pdf`).
</ResponseField>

<ResponseField name="files[].file_size" type="number">
  File size in bytes at upload time.
</ResponseField>

<ResponseField name="files[].file_mtime" type="string">
  File last-modified time (ISO 8601) used for deduplication.
</ResponseField>

<ResponseField name="files[].chunk_count" type="number">
  Content chunks indexed for this file.
</ResponseField>

<ResponseField name="files[].summary_count" type="number">
  Batch summary chunks created (one per 100 content chunks).
</ResponseField>

<ResponseField name="files[].status" type="string">
  `indexed`, `processing`, `failed`, or `file_missing` (path no longer readable).
</ResponseField>

<ResponseField name="files[].path_exists" type="boolean">
  Whether the source file still exists at `absolute_path` inside the container.
</ResponseField>

<ResponseField name="files[].ingested_at" type="string">
  When the file was last successfully indexed (ISO 8601).
</ResponseField>

<ResponseField name="files[].last_error" type="string | null">
  Error from the last failed upload attempt, or `null`.
</ResponseField>

<ResponseField name="files[].metadata" type="object">
  Custom metadata merged from the upload request.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "success",
    "count": 1,
    "files": [
      {
        "file_id": "a1b2c3d4e5f67890",
        "absolute_path": "/uploads/document.pdf",
        "filename": "document.pdf",
        "file_type": ".pdf",
        "file_size": 125440,
        "file_mtime": "2026-06-05T18:50:08Z",
        "chunk_count": 3,
        "summary_count": 1,
        "status": "indexed",
        "path_exists": true,
        "ingested_at": "2026-06-05T18:50:20Z",
        "last_error": null,
        "metadata": { "department": "engineering" }
      }
    ]
  }
  ```
</ResponseExample>

## Related

* [Get file](/on-prem/api-references/files/get)
* [CLI: moorcheh list-files](/on-prem/cli/files/list-files)
* [Python: files.list()](/on-prem/python-client/files/list-files)