Supported file formats

The one criterion that matters

Before asking whether a specific format works, ask yourself a simpler question: does the file contain extractable text? The xAI Files API handles text files. If any tool can pull characters out of it without optical character recognition, the document is likely accepted. Pure binary files—images, audio, video—don’t belong here; for an image, the correct approach is input_image in the Responses API, not the Files API.

This single criterion explains most rejections you’ll encounter. It also explains why a financial report PDF works perfectly while a PDF from a desktop scanner fails: the first carries a text layer, the second is just a series of photos of pages.

The four supported categories

Supported formats fall into four categories, each with its preferred uses.

On the office document side, PDF remains the most common format, and Grok extracts its text, tables, and section breakdown. A Word DOCX retains its formatting—bold, italics, lists—in the extraction, just like its open-source equivalent ODT. EPUB becomes interesting as soon as you work on long publications, a white paper, or an entire manual, and RTF, though older, remains common enough to support.

Source code is where the Files API distinguishes itself most clearly from copy-paste. Sending payment.py in full rather than an isolated function changes the nature of the analysis: Grok sees the imports, dependencies, and file organization, and can therefore spot that an exception is caught thirty lines up or that a constant defined at the top contradicts a comment at the bottom. 80+ languages with text-based syntax are covered.

Data formats primarily serve quantitative analysis. A CSV of monthly sales lets Grok calculate variances, spot seasonality, and summarize a dataset of several thousand lines; a JSON configuration or API response gives it access to the hierarchy and relationships between fields, which a flattened table wouldn’t show. JSON-LD adds semantic context to linked data, and vCard covers contact cards. Finally, TXT and MD work as expected, with Markdown offering the advantage of conveying a lightweight structure of headings and lists.

Common pitfalls

Four constraints come up constantly in production. The first is size: 48 MB per file, beyond which you must split the document. The second is encoding: your files must be in UTF-8, and an export in ISO-8859 or Windows-1252 will produce corrupted accented characters, sometimes subtly—an `é` becoming `é` in the middle of a contract goes unnoticed until a search finds nothing. The third is the lack of image processing: PNG, JPG, or GIF don’t belong here, you must use input_image. The fourth is the case of a scanned PDF without an OCR text layer, which will be accepted on upload but return no results when queried.

This last situation calls for a simple habit: before uploading a batch of PDFs of uncertain origin, open one and try to select a paragraph with the mouse. If nothing selects, your documents must go through OCR processing beforehand.

Choose the most structured format possible

When the same information exists in multiple forms, always choose the most structured one. For report analysis, prefer the original PDF or DOCX, which preserve the hierarchy, rather than a flat text export. For data analysis, a CSV for tables and JSON for hierarchical data will give better results than a spreadsheet export transformed into plain text. For a code review, send the original source file with its original extension. For documentation, Markdown or PDF works depending on what you have at the source. The rule boils down to one sentence: every level of structure you keep is a level of context the model won’t have to reconstruct.

Key takeaways

• The Files API supports documents (PDF, DOCX, EPUB), code (80+ languages), data (CSV, JSON), and plain text
• The limit is 48 MB per file in UTF-8 encoding
• Images and binary files are not supported—use input_image for images
• Prefer the most structured format possible to get better analysis