Retrieve File Metadata

Overview The Retrieve File Metadata API provides detailed information about a specific file in your organization. Use this endpoint to check file status, size, format, and other metadata before processing or using the file in other operations. Key Features

Complete file metadata including size, format, and timestamps
Processing status for uploaded files
Purpose and usage tracking for organization
Expiration information for temporary files
Error details if file processing failed

Common Use Cases

File Verification
Storage Management
Error Handling

Verify file details before processing:

# Check file before using in vector storage
file = client.files.retrieve("file-abc123")

if file.status == "processed" and file.bytes > 0:
    # File is ready for use
    process_file(file.id)

Monitor file metadata for organization:

# Check file expiration
file = client.files.retrieve("file-abc123")

if file.expires_at and file.expires_at < time.time():
    print("Warning: File will expire soon")

Handle file processing errors:

# Check processing status
file = client.files.retrieve("file-abc123")

if file.status == "error":
    print(f"File processing failed: {file.status_details}")

Path Parameters

Parameter	Type	Required	Description
`file_id`	string	Yes	The ID of the file to retrieve

Example Request

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

Response

{
  "id": "file-abc123",
  "object": "file",
  "bytes": 175842,
  "created_at": 1699061776,
  "filename": "training_data.jsonl",
  "purpose": "fine-tune",
  "status": "processed",
  "status_details": null
}

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	Original name of the uploaded file
`purpose`	string	The purpose specified when the file was uploaded
`status`	string	Processing status: “uploaded”, “processed”, “error”
`status_details`	string	Additional details about the status (if applicable)

File Status

Status	Description
`uploaded`	File has been uploaded but not yet processed
`processed`	File has been successfully processed and is ready for use
`error`	An error occurred during file processing

Error Responses

Status Code	Error Type	Description
`404`	`file_not_found`	File with the specified ID does not exist
`401`	`authentication_error`	Invalid or missing API key
`403`	`permission_denied`	File belongs to a different organization

Use Cases

File Validation
File Information
Wait for Processing

Check if a file is ready for use:

def validate_file_ready(file_id):
    """Check if file is processed and ready for use"""
    try:
        file = client.files.retrieve(file_id)
        
        if file.status == "processed":
            print(f"✅ File {file.filename} is ready")
            return True
        elif file.status == "uploaded":
            print(f"⏳ File {file.filename} is still processing")
            return False
        elif file.status == "error":
            print(f"❌ File {file.filename} failed to process: {file.status_details}")
            return False
            
    except Exception as e:
        print(f"❌ Error retrieving file: {e}")
        return False

Display comprehensive file information:

def display_file_info(file_id):
    """Display detailed file information"""
    file = client.files.retrieve(file_id)
    
    # Convert timestamp to readable date
    import datetime
    created_date = datetime.datetime.fromtimestamp(file.created_at)
    
    print(f"📄 File Information")
    print(f"   ID: {file.id}")
    print(f"   Name: {file.filename}")
    print(f"   Size: {file.bytes:,} bytes ({file.bytes / 1024 / 1024:.2f} MB)")
    print(f"   Purpose: {file.purpose}")
    print(f"   Status: {file.status}")
    print(f"   Created: {created_date.strftime('%Y-%m-%d %H:%M:%S')}")
    
    if file.status_details:
        print(f"   Details: {file.status_details}")

Wait for file processing to complete:

import time

def wait_for_file_processing(file_id, max_wait_seconds=300):
    """Wait for file to be processed"""
    start_time = time.time()
    
    while time.time() - start_time < max_wait_seconds:
        file = client.files.retrieve(file_id)
        
        if file.status == "processed":
            print(f"✅ File processing complete")
            return True
        elif file.status == "error":
            print(f"❌ File processing failed: {file.status_details}")
            return False
        
        print(f"⏳ Still processing... ({file.status})")
        time.sleep(5)
    
    print(f"⏰ Timeout waiting for file processing")
    return False

# Usage
if wait_for_file_processing("file-abc123"):
    print("File is ready to use!")

Best Practices

Authorizations

Authorization

string

header

required

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

Path Parameters

file_id

string

required

The ID of the file to retrieve

Response

200

File metadata

Getting Started

AI Inference

Embeddings

Files

Vectors

Deployments

AgentBox

Retrieve File Metadata

Example Request

Response

Response Fields

File Status

Error Responses

Use Cases

Best Practices

Authorizations

Path Parameters

Response

Getting Started

AI Inference

Embeddings

Files

Vectors

Deployments

AgentBox

​Example Request

​Response

​Response Fields

​File Status

​Error Responses

​Use Cases

​Best Practices

Authorizations

Path Parameters

Response

Example Request

Response

Response Fields

File Status

Error Responses

Use Cases

Best Practices