Track Files API upload progress with on_progress

Large Files API uploads (up to 512 MB) can take a while on slow links. The xAI Python SDK client.files.upload accepts an on_progress callback so you can print a bar, update a UI, or log bytes without wrapping the HTTP client yourself.

Python SDK

The callback receives (bytes_uploaded, total_bytes). total_bytes can be 0 until the client knows the size, so guard the percentage.

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

def progress_callback(bytes_uploaded: int, total_bytes: int):
    percentage = (bytes_uploaded / total_bytes) * 100 if total_bytes else 0
    mb_uploaded = bytes_uploaded / (1024 * 1024)
    mb_total = total_bytes / (1024 * 1024)
    print(f"Progress: {mb_uploaded:.2f}/{mb_total:.2f} MB ({percentage:.1f}%)")

file = client.files.upload(
    "/path/to/large-file.pdf",
    on_progress=progress_callback,
)
print(f"Uploaded: {file.filename} ({file.id})")

You can combine on_progress with expires_after (seconds or datetime.timedelta) so a large ephemeral upload still auto-deletes. Field order still matters on raw multipart: TTL fields before file. See Set a TTL on Files API uploads.

When you skip the callback

Path, bytes, and open-handle uploads all work without on_progress. OpenAI-compatible files.create and plain curl -F do not expose this SDK hook; use your HTTP client's own progress meter there.

Pitfalls

• Assuming total_bytes is always nonzero on the first tick.
• Treating console Files storage as the same bill as SuperGrok's weekly pool on grok.com.
• Leaving a 512 MB permanent file after a one-off job; set a TTL or delete when done (List, download, and delete Files API uploads).