List, download, and delete Files API uploads

After upload (Set a TTL on Files API uploads), manage files on https://api.x.ai/v1/files with your team XAI_API_KEY. Max size is 512 MB per file. You can also browse them on the Files page in the xAI Console.

List (paginated)

limit defaults to 100 and caps at 100. order is asc or desc (default desc). sort_by is created_at, filename, or size (default created_at). Pass pagination_token from the previous page for the next page. A page shorter than limit means you are done.

curl "https://api.x.ai/v1/files?limit=10&order=desc&sort_by=created_at" \
  -H "Authorization: Bearer $XAI_API_KEY"

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))
page_size = 100
token = None
all_files = []

while True:
    response = client.files.list(
        limit=page_size,
        order="desc",
        sort_by="created_at",
        pagination_token=token,
    )
    all_files.extend(response.data)
    if len(response.data) < page_size:
        break
    token = response.pagination_token

print(f"Total files: {len(all_files)}")

Get metadata

curl https://api.x.ai/v1/files/file-abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"

The file object includes id, filename, bytes, created_at (Unix seconds), expires_at (null when permanent), object ("file"), and purpose (stored for SDK compatibility; xAI does not enforce it).

Download content

curl https://api.x.ai/v1/files/file-abc123/content \
  -H "Authorization: Bearer $XAI_API_KEY" \
  --output downloaded.pdf

content = client.files.content("file-abc123")
with open("downloaded.pdf", "wb") as f:
    f.write(content)

The endpoint streams, so large files do not need to buffer entirely at the API layer. Prefer streaming to disk in your client for big payloads.

Delete

curl -X DELETE https://api.x.ai/v1/files/file-abc123 \
  -H "Authorization: Bearer $XAI_API_KEY"

Manual delete works before a TTL elapses. After expires_at, list/get/content return not found and the id cannot be referenced.

Pitfalls

• Assuming list returns every file in one call — walk pagination_token until a short page.
• Treating purpose as a permission gate — it is echoed for OpenAI SDK compatibility.
• Keeping expired ids in your app state — they stop working at expires_at.