Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

List files

client.files.list(query?, options?): CursorPage<FileObject { id, bytes, created_at, 6 more } >
GET
/files

Returns a list of files.

List files

import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.files.list();

  for await (const file of list) {
    console.log(file);
  }
}

main();
Response example
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "expires_at": 1677614202,
      "filename": "salesOverview.pdf",
      "purpose": "assistants",
      "status": "processed"
    },
    {
      "id": "file-abc456",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "expires_at": 1677614202,
      "filename": "puppy.jsonl",
      "purpose": "fine-tune",
      "status": "processed"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}
Parameters
query: FileListParams { after, limit, order, purpose }
after?: string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

limit?: number

A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

order?: "asc" | "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

purpose?: string

Only return files with the given purpose.

Returns
FileObject { id, bytes, created_at, 6 more }

The File object represents a document that has been uploaded to OpenAI.

id: string

The file identifier, which can be referenced in the API endpoints.

bytes: number

The size of the file, in bytes.

created_at: number

The Unix timestamp (in seconds) for when the file was created.

formatunixtime
filename: string

The name of the file.

object: "file"

The object type, which is always file.

purpose: "assistants" | "assistants_output" | "batch" | 5 more

The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.

status: "uploaded" | "processed" | "error"

Deprecated.

Deprecated. The current status of the file, which can be either uploaded, processed, or error.

expires_at?: number

The Unix timestamp (in seconds) for when the file will expire.

formatunixtime
status_details?: string

Deprecated.

Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Returns Examples
Response example
{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "expires_at": 1677614202,
      "filename": "salesOverview.pdf",
      "purpose": "assistants",
      "status": "processed"
    },
    {
      "id": "file-abc456",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "expires_at": 1677614202,
      "filename": "puppy.jsonl",
      "purpose": "fine-tune",
      "status": "processed"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}