Files and Batch Processing in AI – A Hands‑On Guide to the Claude API

When you start feeding an LLM a mountain of PDFs, Word docs, or CSVs, the first thing you notice is the repetitive upload dance – every call seems to ask for the same bytes again. The Claude API tries to fix that with a pair of handy tools: the Files API and the Message Batches API.

Files API – upload once, call forever

Think of the Files API as a library shelf inside Anthropic’s cloud. You drop a file on the shelf, you get a file_id, and from that moment on you can point to the same document in any number of future messages. No more re‑sending a 10‑MB PDF for every question you ask the model.

In Python it looks something like this:

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 payload, you just embed a document block that references that file_id:

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

There are a few quirks worth noting. First, files you upload cannot be downloaded again – they’re essentially write‑only. Only files generated by a skill or the code‑execution tool are ever downloadable. Second, the storage is workspace‑wide: any API key belonging to the same workspace can reference any uploaded file. That’s great for collaboration, but it also means you should never trust a raw file_id that comes directly from an end user. Keep a mapping in your own database so you always know who owns which file.

Limits are pretty generous – up to 500 MB per file and 500 GB total for the organization. If you need to change a file, you actually have to upload a fresh version and delete the old one; there’s no rename or edit operation. And if the document block doesn’t support a format (say a .docx), convert it to plain text or PDF first.

Message Batches API – bulk‑process without the wait

While the regular Messages API gives you an immediate response, the Batches API lets you throw a whole lot of requests at the model and collect the answers later. It’s ideal for non‑urgent workloads like indexing a corpus, generating many summaries, or running a nightly data‑cleaning routine.

Here’s a quick sketch of creating a batch in Python:

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="summary‑1",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": "Summarize chapter 3"}],
            ),
        ),
        # …more Request objects…
    ]
)

Every request needs a unique custom_id. The API may return results in a different order than you submitted, so that identifier is your hook for stitching answers back to the right input.

Batch limits are pretty clear: a single batch can hold up to 100 000 requests or 256 MB of payload, whichever comes first. Most batches finish within an hour, but the system will give up after 24 hours if it can’t finish. Once done, results are stored as a .jsonl file for 29 days – you can stream it line‑by‑line instead of downloading the whole thing, which is a lifesaver when the batch is huge.

Pricing is also friendly. Whereas normal messages are billed at the standard token rate, batch processing enjoys a 50 % discount on token usage. That makes a massive difference when you’re crunching thousands of documents.

Mixing batch processing with prompt caching

If many of your batch requests share a big system prompt or a common reference document, you can add a cache_control block to each request. The API will try to serve that shared content from cache, which stacks on top of the batch discount. In practice, cache hit rates vary – some workloads see 30 % hits, others hit close to 100 % – but it’s almost always cheaper than sending the same text over and over.

Practical tips to keep things sane

• Start with a single‑request “dry run” against the regular Messages endpoint to make sure your payload is valid.
• Store a mapping of custom_id → user request in your DB so you can reconcile results later.
• Periodically purge old files; the free‑delete action means you won’t be charged for storage you no longer need.
• Watch the 24‑hour batch expiration – if a batch is critical, schedule a retry before the deadline.

By combining the Files API’s one‑time‑upload model with the asynchronous power of Message Batches, you can turn a slow, expensive document‑heavy workflow into a scalable, cost‑effective pipeline. Give it a try, tweak the limits to your use case, and let the Claude API handle the heavy lifting.