---
title: "List files"
method: GET
path: "/files"
tags: ["Files"]
---

# List files

`GET /files`

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

## Query parameters

- `limit` integer
- `cursor` string
- `state` 'pending' | 'ready' | 'failed' | 'deleted' — 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.
- `purpose` 'input' | 'reference' — 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.

## Response `200`

A page of files

- 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` File[], required — Files in this page.
    - `id` string, uuid, required — File identifier, referenced as ImageRef.file_id.
    - `filename` string, nullable — Original filename supplied at upload, if any.
    - `mime_type` string, required — MIME type of the stored bytes (for example, image/jpeg).
    - `size_bytes` integer, required — Size of the stored object in bytes.
    - `purpose` 'input' | 'reference', required — 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.
    - `state` 'pending' | 'ready' | 'failed' | 'deleted', required — 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.
    - `failure_reason` string, nullable — Human-readable reason when state is failed.
    - `expires_at` string, date-time, nullable — 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.
    - `created_at` string, date-time, required — Creation timestamp.
    - `deleted_at` string, date-time, nullable — Soft-delete timestamp, if the file was deleted.
    - `user_id` string, nullable — The opaque end-user tag supplied at upload, echoed back unchanged. Abuse-attribution only; not an access-control primitive.
  - `has_more` boolean, required — Whether more files exist beyond this page.
  - `next_cursor` string, nullable — Opaque cursor for the next page, when has_more is true.

## Other responses

- `401` — Missing or invalid API key
- `422` — Invalid cursor

---

[API](https://skmtc.net/lumalabs/apis/luma-agents-api.md) · [All operations](https://skmtc.net/lumalabs/apis/luma-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lumalabs/luma-agents-api/versions/2135bbde249c/schema)