Manage your files: list, retrieve, delete — Collections, RAG & Files

What happens after the hundredth upload

Uploading a file takes three seconds; finding the one you sent six weeks ago takes much longer if you haven’t planned ahead. After the initial tests, an account accumulates dozens then hundreds of documents. Some are outdated, others are duplicated, and others are referenced by applications still running. The Files API exposes three operations to manage this inventory: list, retrieve, and delete. They seem secondary while volume is low, but become indispensable later.

Take inventory

GET /v1/files returns all files uploaded to your account:

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

The response is a paginated list, with each entry repeating the metadata seen at upload:

{
  "object": "list",
  "data": [
    {
      "id": "file_abc123",
      "object": "file",
      "bytes": 2458901,
      "created_at": 1710000000,
      "filename": "rapport-annuel.pdf",
      "purpose": "assistants"
    },
    {
      "id": "file_def456",
      "object": "file",
      "bytes": 15230,
      "created_at": 1710100000,
      "filename": "données-clients.csv",
      "purpose": "assistants"
    }
  ]
}

This view solves three very concrete situations: recovering a file_id you didn’t save at upload time, checking the actual size of a document that seems abnormally heavy, and spotting deletion candidates by sorting on created_at. It’s also the only place where you’ll see at a glance that the same report was sent three times under three different names.

Verify a specific file

When you already know the identifier, GET /v1/files/{file_id} queries a single document:

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

You retrieve the same information as at upload: identifier, name, size, creation date, and purpose. The most useful use of this call is defensive. Before launching a process that references a file_id stored for a long time in your database, a check lasting a few milliseconds saves you from an error in the middle of a chain of billed requests.

Delete, and what to check before

Deletion is done with DELETE /v1/files/{file_id} and the response confirms the operation:

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

{
  "id": "file_abc123",
  "object": "file",
  "deleted": true
}

Two checks are required before pulling the trigger. First, the file may be referenced in a collection—a concept we will detail in upcoming lessons. Deleting it via the Files API does not automatically remove it from the collection, leaving you with a dead reference in your index: remove it from the collection first, then from storage. Next, the file may be used by active workflows; any application keeping this file_id in its database will receive errors as soon as deletion is performed, often in production and rarely while you are monitoring logs.

Keep your storage clean

Naming is your first management tool, because the original name is kept in the metadata and constitutes the only readable marker in a list of a hundred entries. rapport-q1-2026.pdf will mean something to you in eight months; document.pdf never will. The same reasoning applies to api-specs-v2.json versus data.json. Make this a habit when you prepare the file on your disk, not at upload time: it is the local name that is transmitted.

Uploaded files remain stored indefinitely, without automatic expiration. A quarterly cleanup routine is enough to avoid drift, in three steps:

List your files with GET /v1/files
Identify those no longer in use, by creation date or name
Delete them with DELETE /v1/files/{file_id}

Three error codes come up in these operations and are diagnosed immediately. A 404 signals a non-existent or already deleted file, a typical case of a cleanup script run twice. A 401 comes from a missing or invalid API key, often an environment variable not loaded in the current shell. A 413 indicates the file exceeds the allowed 48 MB and occurs at upload, not during management.

Key takeaways

GET /v1/files lists all your files with their metadata
GET /v1/files/{id} retrieves a specific file
DELETE /v1/files/{id} permanently deletes a file
Name your files explicitly to facilitate management
Check dependencies (collections, workflows) before deleting