List Files

Overview The List Files API provides a comprehensive view of all files uploaded to your Gravix Layer organization. Use this endpoint to manage your file storage, monitor usage, and organize files by purpose and metadata. Key Features

Purpose-based filtering to organize files by use case
Pagination support for large file collections
Detailed metadata including size, creation date, and status
Real-time file status tracking
Bulk operations support for file management

Common Use Cases

File Management
Storage Auditing
Purpose Organization

Monitor and organize your uploaded files:

# List all files with metadata
files = client.files.list()

for file in files.data:
    print(f"{file.filename}: {file.bytes} bytes, {file.purpose}")

Track storage usage and costs:

# Calculate total storage usage
files = client.files.list()
total_bytes = sum(file.bytes for file in files.data)

print(f"Total storage: {total_bytes / 1024 / 1024:.1f} MB")

Filter files by specific use cases:

# List only fine-tuning datasets
training_files = client.files.list(purpose="fine-tune")

# List user data files for RAG
rag_files = client.files.list(purpose="user_data")

Query Parameters

Parameter	Type	Required	Description
`purpose`	string	No	Filter files by purpose. One of: `batch`, `batch_output`, `fine-tune`, `vision`, `user_data`, `evals`
`limit`	integer	No	Number of files to return (default: 20, max: 100)
`after`	string	No	Cursor for pagination. Use the `id` of the last file from the previous page

Example Requests

curl https://api.gravixlayer.com/v1/files \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 175842,
      "created_at": 1699061776,
      "filename": "training_data.jsonl",
      "purpose": "fine-tune"
    },
    {
      "id": "file-def456", 
      "object": "file",
      "bytes": 245832,
      "created_at": 1699061234,
      "filename": "image_dataset.zip",
      "purpose": "vision"
    }
  ],
  "has_more": false
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the file
`object`	string	Always “file”
`bytes`	integer	Size of the file in bytes
`created_at`	integer	Unix timestamp of when the file was created
`filename`	string	Name of the uploaded file
`purpose`	string	Purpose specified when uploading

Pagination

Use the after parameter to paginate through results:

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

# Get next page using the last file ID
if files.has_more:
    next_files = client.files.list(
        limit=20,
        after=files.data[-1].id
    )

Error Responses

Status Code	Error Type	Description
`400`	`invalid_request_error`	Invalid query parameters
`401`	`authentication_error`	Invalid or missing API key
`429`	`rate_limit_exceeded`	Too many requests

Use Cases

File Management
Purpose-Based Filtering
Pagination Example

Monitor and manage your uploaded files:

def manage_files():
    files = client.files.list()
    
    for file in files.data:
        # Check file age
        age_days = (time.time() - file.created_at) / (24 * 60 * 60)
        
        print(f"File: {file.filename}")
        print(f"  Size: {file.bytes / 1024 / 1024:.1f} MB")
        print(f"  Age: {age_days:.1f} days")
        print(f"  Purpose: {file.purpose}")
        
        # Flag old files for cleanup
        if age_days > 30 and file.purpose in ["batch", "user_data"]:
            print(f"  ⚠️  Consider deleting old file")

Filter files by their intended use:

def audit_files_by_purpose():
    purposes = ["fine-tune", "vision", "batch", "user_data"]
    
    for purpose in purposes:
        files = client.files.list(purpose=purpose)
        total_size = sum(file.bytes for file in files.data)
        
        print(f"{purpose.upper()} files:")
        print(f"  Count: {len(files.data)}")
        print(f"  Total size: {total_size / 1024 / 1024:.1f} MB")
        print("---")

Process all files with pagination:

def process_all_files():
    all_files = []
    after = None
    
    while True:
        files = client.files.list(limit=100, after=after)
        all_files.extend(files.data)
        
        if not files.has_more:
            break
            
        after = files.data[-1].id
    
    print(f"Total files: {len(all_files)}")
    return all_files

Authorizations

Authorization

string

header

required

API key authentication. Get your API key from the Gravix Layer Dashboard.

Query Parameters

purpose

string

Filter files by purpose

limit

integer

default:20

Number of files to return

Required range: x <= 100

order

enum<string>

default:desc

Sort order

Available options:

asc,

desc

after

string

Pagination cursor

Response

200

List of files

Getting Started

AI Inference

Embeddings

Files

Vectors

Deployments

AgentBox

Response

Response Fields

Error Responses

Use Cases

Authorizations

Query Parameters

Response

Getting Started

AI Inference

Embeddings

Files

Vectors

Deployments

AgentBox

​Response

​Response Fields

​Pagination

​Error Responses

​Use Cases

Authorizations

Query Parameters

Response

Response

Response Fields

Pagination

Error Responses

Use Cases