## List files

`files.list(FileListParams**kwargs)  -> FileList`

**get** `/files`

List the files in your namespace, newest first. Keyset-paginated: when has_more is true, pass next_cursor back as cursor.

### Parameters

- `cursor: Optional[str]`

  Opaque pagination cursor from a prior response's next_cursor.

- `limit: Optional[int]`

  Maximum files to return (1–100). Defaults to 25.

- `purpose: Optional[FilePurpose]`

  Filter to files with this purpose.

  - `"input"`

  - `"reference"`

- `state: Optional[FileState]`

  Filter to files in this state.

  - `"pending"`

  - `"ready"`

  - `"failed"`

  - `"deleted"`

### Returns

- `class FileList: …`

  Keyset-paginated page of files, newest first. When has_more is true, pass next_cursor back as the cursor query parameter to fetch the next page. next_cursor is opaque.

  - `data: List[File]`

    Files in this page.

    - `id: str`

      File identifier, referenced as ImageRef.file_id.

    - `created_at: datetime`

      Creation timestamp.

    - `mime_type: str`

      MIME type of the stored bytes (for example, image/jpeg).

    - `purpose: FilePurpose`

      How the file is intended to be used in a generation. `input` is the primary subject (e.g. the source image for an edit); `reference` is style/content guidance.

      - `"input"`

      - `"reference"`

    - `size_bytes: int`

      Size of the stored object in bytes.

    - `state: FileState`

      Lifecycle state of an uploaded file. `pending` until bytes are received and the ingest pipeline runs; `ready` once it can be referenced from a generation; `failed` if ingest/moderation rejected it; `deleted` after a soft-delete.

      - `"pending"`

      - `"ready"`

      - `"failed"`

      - `"deleted"`

    - `deleted_at: Optional[datetime]`

      Soft-delete timestamp, if the file was deleted.

    - `expires_at: Optional[datetime]`

      TTL set at upload, if any. After this time Luma may automatically delete the file and reclaim its bytes — you don't need to call DELETE yourself.

    - `failure_reason: Optional[str]`

      Human-readable reason when state is failed.

    - `filename: Optional[str]`

      Original filename supplied at upload, if any.

    - `user_id: Optional[str]`

      The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive.

  - `has_more: bool`

    Whether more files exist beyond this page.

  - `next_cursor: Optional[str]`

    Opaque cursor for the next page, when has_more is true.

### Example

```python
import os
from luma_agents import Luma

client = Luma(
    auth_token=os.environ.get("LUMA_AGENTS_API_KEY"),  # This is the default and can be omitted
)
file_list = client.files.list()
print(file_list.data)
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "created_at": "2019-12-27T18:11:19.117Z",
      "mime_type": "mime_type",
      "purpose": "input",
      "size_bytes": 0,
      "state": "pending",
      "deleted_at": "2019-12-27T18:11:19.117Z",
      "expires_at": "2019-12-27T18:11:19.117Z",
      "failure_reason": "failure_reason",
      "filename": "filename",
      "user_id": "user_id"
    }
  ],
  "has_more": true,
  "next_cursor": "next_cursor"
}
```