Skip to content
Luma Agents
lumalabs.ai
API Reference
Files

List files

client.files.list(FileListParams { cursor, limit, purpose, state } query?, RequestOptionsoptions?): FileList { data, has_more, next_cursor }
GET/files

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

ParametersExpand Collapse
query: FileListParams { cursor, limit, purpose, state }
cursor?: string

Opaque pagination cursor from a prior response's next_cursor.

limit?: number

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

minimum1
maximum100
purpose?: FilePurpose

Filter to files with this purpose.

One of the following:
"input"
"reference"
state?: FileState

Filter to files in this state.

One of the following:
"pending"
"ready"
"failed"
"deleted"
ReturnsExpand Collapse
FileList { data, has_more, next_cursor }

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: Array<File { id, created_at, mime_type, 8 more } >

Files in this page.

id: string

File identifier, referenced as ImageRef.file_id.

formatuuid
created_at: string

Creation timestamp.

formatdate-time
mime_type: string

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.

One of the following:
"input"
"reference"
size_bytes: number

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.

One of the following:
"pending"
"ready"
"failed"
"deleted"
deleted_at?: string | null

Soft-delete timestamp, if the file was deleted.

formatdate-time
expires_at?: string | null

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.

formatdate-time
failure_reason?: string | null

Human-readable reason when state is failed.

filename?: string | null

Original filename supplied at upload, if any.

user_id?: string | null

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

has_more: boolean

Whether more files exist beyond this page.

next_cursor?: string | null

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

List files

import Luma from 'luma-agents';

const client = new Luma({
  authToken: process.env['LUMA_AGENTS_API_KEY'], // This is the default and can be omitted
});

const fileList = await client.files.list();

console.log(fileList.data);
{
  "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"
}
Returns Examples
{
  "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"
}