API Reference

Files

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List files

FileListPage files().list(FileListParamsparams = FileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/files

Returns a list of files.

ParametersExpand Collapse

FileListParams params

Optional<String> after

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.

Optional<Long> limit

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

Optional<Order> order

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

ASC("asc")

DESC("desc")

Optional<String> purpose

Only return files with the given purpose.

ReturnsExpand Collapse

class FileObject:

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

String id

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

long bytes

The size of the file, in bytes.

long createdAt

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

String filename

The name of the file.

JsonValue; object_ "file"constant"file"constant

The object type, which is always file.

Purpose purpose

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

Accepts one of the following:

ASSISTANTS("assistants")

ASSISTANTS_OUTPUT("assistants_output")

BATCH("batch")

BATCH_OUTPUT("batch_output")

FINE_TUNE("fine-tune")

FINE_TUNE_RESULTS("fine-tune-results")

VISION("vision")

USER_DATA("user_data")

DeprecatedStatus status

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

Accepts one of the following:

UPLOADED("uploaded")

PROCESSED("processed")

ERROR("error")

Optional<Long> expiresAt

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

DeprecatedOptional<String> statusDetails

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

List files

Java

HTTP

TypeScript

Python

Java

Go

Ruby

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileListPage;
import com.openai.models.files.FileListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        FileListPage page = client.files().list();
    }
}

200 example

{
  "data": [
    {
      "id": "id",
      "bytes": 0,
      "created_at": 0,
      "filename": "filename",
      "object": "file",
      "purpose": "assistants",
      "status": "uploaded",
      "expires_at": 0,
      "status_details": "status_details"
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}

Returns Examples

200 example

{
  "data": [
    {
      "id": "id",
      "bytes": 0,
      "created_at": 0,
      "filename": "filename",
      "object": "file",
      "purpose": "assistants",
      "status": "uploaded",
      "expires_at": 0,
      "status_details": "status_details"
    }
  ],
  "first_id": "file-abc123",
  "has_more": false,
  "last_id": "file-abc456",
  "object": "list"
}