Files and Batch Processing in AI: A Practical Guide

When you start feeding an AI model with real‑world documents—PDFs, spreadsheets, images—the naive approach quickly turns into a nightmare. You keep re‑uploading the same file over and over, each request burns tokens, and the latency spikes. That’s where the Files API and Message Batches API step in, giving you a sort of "upload‑once, use‑many‑times" workflow and a cheap way to crunch thousands of prompts in the background.

Files API in a nutshell

Think of the Files API as a cloud‑based filing cabinet. You drop a file into Anthropic’s storage, you get a file_id back, and from that moment on you simply point to the ID whenever you need the document inside a message request. No more plopping binary blobs into every payload. The only catch? Once a file lands there, you can’t download it again—except for those generated by a skill or the code‑execution tool, which are specially marked as downloadable.

Here’s a quick Python sketch:

uploaded = client.beta.files.upload( file=("report.pdf", open("/path/to/report.pdf", "rb"), "application/pdf") ) file_id = uploaded.id

Later, when you build a message, you embed the ID like this:

{ "type": "document", "source": {"type": "file", "file_id": "file_xyz123"} }

Images get an image block, tabular data for the code‑execution tool gets a container_upload block, and so on. Pricing is simple: the content of the file counts as normal input tokens, but the upload, list, delete, and even the occasional download (when allowed) are free.

One file, many users

Uploaded assets are global to the whole workspace. Any API key that lives inside your organization can reference any file_id. That sounds convenient, but it also means you must guard against trusting a user‑supplied ID. A malicious client could try to slip in someone else’s file ID and peek at data they shouldn’t see. The safe pattern is to keep a mapping table in your own database that ties a user’s logical file name to the internal file_id you received at upload time.

Technical limits are worth noting: each file can be at most 500 MB, and the entire org gets 500 GB of storage. You can’t rename or edit a file after it’s uploaded—just delete it and upload a fresh copy if you need a change. Files hang around indefinitely until you explicitly delete them, and deletions are permanent.

Messages API vs. Message Batches API

The classic Messages API is synchronous: you send a prompt, the model replies right away, and you pay the full token price. It’s perfect for chatty, real‑time apps. The Message Batches API, on the other hand, is asynchronous and dramatically cheaper—roughly half the token cost. You bundle up to 100 000 individual requests (or 256 MB of total payload) into a single batch, fire it off, and come back later for the results.

Key trade‑offs look like this:

• Synchronous vs. Asynchronous: instant answer versus “come back later.”
• Pricing: full token price versus about 50 % of that.
• Volume: one‑off calls versus massive bulk jobs.

Creating a batch

Every request inside a batch needs a unique custom_id. That tag is how you match the eventual result to the original prompt, because batches may return results out of order. A tiny example in Python:

message_batch = client.messages.batches.create( requests=[ Request( custom_id="first‑doc‑analysis", params=MessageCreateParamsNonStreaming( model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarize the attached PDF"}], ), ), # … add more Request objects here … ] )

Once the batch is submitted, the service starts chewing through the jobs. Most batches finish within an hour, but there’s a hard 24‑hour expiration clock. After that, the batch is discarded and you’ll have to resend whatever was left.

Fetching the results

When the batch is done, you pull the results back. They arrive as a .jsonl stream—one JSON line per request. Streaming is recommended; downloading the whole file at once can be memory‑hungry for large batches.

for result in client.messages.batches.results("msgbatch"): match result.result.type: case "succeeded": print(f"✅ {result.custom_id} succeeded") case "errored": print(f"❌ {result.custom_id} failed")

These results stay available for 29 days, after which they evaporate. Keep that in mind if you need long‑term audit logs.

Marrying batches with prompt caching

If many of your batch requests share a huge system prompt or a big reference document, you can sprinkle identical cache_control blocks across them. The API will try to serve that shared content from cache, applying the cheap cache token price on top of the batch discount. Because the batch runs concurrently, cache hits aren’t guaranteed, but in practice you’ll see hit rates anywhere from 30 % to nearly 100 % depending on how repetitive your workload is.

Practical tips to stay sane

• Run a single request in “synchronous” mode first as a dry‑run. It helps you validate payloads before you throw them into a massive batch.
• Keep a local manifest of custom_id ↔︎ request mapping; it’s a lifesaver when you need to debug a specific failure.
• Use short, descriptive custom_id strings—something like invoice‑2024‑Q1‑summary makes tracing a breeze.
• Remember to delete files you no longer need; otherwise you’ll hit the 500 GB org limit sooner than expected.

All in all, the Files API and Message Batches API give you a powerful combo: reusable uploads that cut down on token waste, and bulk asynchronous processing that slashes costs dramatically. With a few good housekeeping habits, you can scale from a handful of ad‑hoc prompts to a production‑grade document‑processing pipeline without breaking the bank.