List Files

Returns a list of files belonging to the user’s organization

Method Signature

client.files.list(
    after: Optional[str] = None,
    limit: Optional[int] = None,
    order: Literal["asc", "desc"] = "desc",
    purpose: Optional[str] = None
) -> SyncCursorPage[FileObject]

Parameters

after · str

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 to fetch the next page of the list.

limit · int · default: "10000"

A limit on the number of objects to be returned.

• Range: 1 to 10,000
• Default: 10,000

order · Literal['asc', 'desc'] · default: "desc"

Sort order by the created_at timestamp of the objects.

• asc - Ascending order (oldest first)
• desc - Descending order (newest first)

purpose · str

Only return files with the given purpose.

Valid purposes:

• assistants
• batch
• fine-tune
• vision
• user_data
• evals

Response

Returns a paginated list of FileObject instances.

class FileObject(BaseModel):
    id: str  # File identifier
    bytes: int  # File size in bytes
    created_at: int  # Unix timestamp
    filename: str  # Original file name
    object: Literal["file"]  # Always "file"
    purpose: str  # File purpose
    status: Literal["uploaded", "processed", "error"]  # Processing status
    expires_at: Optional[int]  # Unix timestamp when file expires

Examples

List All Files

from openai import OpenAI

client = OpenAI()

files = client.files.list()

for file in files:
    print(f"{file.id}: {file.filename} ({file.purpose})")

List Fine-tuning Files Only

files = client.files.list(purpose="fine-tune")

for file in files:
    print(f"{file.filename} - {file.bytes} bytes")

Paginate Through Files

# Get first page
page = client.files.list(limit=10)

for file in page:
    print(file.filename)

# Get next page using the last file ID as cursor
if page.data:
    last_file_id = page.data[-1].id
    next_page = client.files.list(limit=10, after=last_file_id)
    
    for file in next_page:
        print(file.filename)

List Files in Ascending Order

files = client.files.list(order="asc", limit=20)

for file in files:
    print(f"{file.created_at}: {file.filename}")

Auto-pagination

# Automatically iterate through all pages
for file in client.files.list():
    print(f"{file.id}: {file.filename}")
    # This will automatically fetch next pages as needed

Filter and Process Files

from datetime import datetime

files = client.files.list(purpose="fine-tune")

for file in files:
    created_date = datetime.fromtimestamp(file.created_at)
    size_mb = file.bytes / (1024 * 1024)
    
    print(f"File: {file.filename}")
    print(f"  Created: {created_date}")
    print(f"  Size: {size_mb:.2f} MB")
    print(f"  Status: {file.status}")
    print()

Async Usage

from openai import AsyncOpenAI

client = AsyncOpenAI()

# List files asynchronously
files = client.files.list(purpose="assistants")

async for file in files:
    print(f"{file.filename}: {file.status}")

Pagination Details

The list() method returns a SyncCursorPage object that supports:

• Iteration: Automatically fetches pages as you iterate
• Manual pagination: Use after parameter with the last object ID
• Page size control: Use limit to control how many objects per page

page = client.files.list(limit=5)

# Check if there are more pages
print(f"Has more: {page.has_next_page()}")

# Access the data directly
print(f"Files in this page: {len(page.data)}")

# Get next page
if page.has_next_page():
    next_page = page.get_next_page()

Notes

• Default limit is 10,000 files per request
• Files are sorted by created_at timestamp
• Use pagination for large file lists to avoid memory issues
• The response includes all file metadata except the actual file contents
• Use the retrieve content endpoint to download file contents