How to Process Thousands of Documents with the Claude API

To process thousands of documents with the Claude API, use the Message Batches API: package your requests into a single batch job, submit it once, and retrieve all results when processing completes. This approach cuts your API costs in half compared to real-time calls and is purpose-built for large-scale, offline workloads like document extraction, bulk classification, and content generation.

What Is the Claude Message Batches API?

The Message Batches API is Anthropic's system for submitting large numbers of independent Claude API requests as a single grouped job for asynchronous processing. Instead of sending requests one at a time and waiting for each response, you package up to 100,000 requests into a batch, submit it once, and retrieve all results when processing completes — typically within an hour, with a 24-hour maximum window.

All batch requests are charged at 50% of standard API prices. This discount can be combined with prompt caching discounts, so heavily cached batches can cost significantly less than real-time equivalents. Results are stored for 29 days after batch creation.

When Should You Use Batch Processing Instead of Real-Time Calls?

Batch processing is the right choice when your workload meets three conditions: you have a large volume of independent requests, you can tolerate up to a one-hour turnaround, and cost efficiency matters. Common scenarios include:

• Bulk document data extraction — pulling structured fields like dates, amounts, and entities from thousands of scanned reports
• Sentiment analysis at scale — classifying tens of thousands of customer support tickets before importing into a dashboard
• LLM-as-a-judge evaluations — testing a new prompt against thousands of edge-case inputs before deploying to production
• Content moderation backlogs — reviewing large queues of user posts without saturating the real-time API used for live traffic
• Bulk content generation — writing product descriptions for tens of thousands of SKUs overnight
• Translation pipelines — converting thousands of help-center articles into multiple languages in a single unattended job

Use the standard synchronous API instead when you need an immediate response — for example, responding to a live user in a chat interface or any workflow where latency matters more than cost.

How Do You Process Thousands of Documents with the Claude API? (Step-by-Step)

1. Install the SDK. Install the Anthropic Python or TypeScript SDK, or use the REST API directly with your API key.
2. Build your request list. Create one request object per document. Each object needs a unique custom_id string (you choose this) and a params object containing standard Messages API parameters — model, max_tokens, messages, and any other options your task requires.
3. Submit the batch. Call the batch creation endpoint (or client.messages.batches.create() in the SDK), passing your list of request objects. The API returns a batch object with an ID and a processing status.
4. Poll for completion. Periodically call the batch retrieval endpoint (or client.messages.batches.retrieve(batch_id)) and check whether the processing status equals ended.
5. Download results. When processing is complete, download the results file. Results are delivered as a JSONL file — one JSON object per line. Each line contains the custom_id you assigned and either a result message or an error.
6. Match results to originals. Use the custom_id field to match each result back to its original request, since results are not guaranteed to be in submission order.

What Does the Code Look Like?

Here is a minimal Python example that classifies customer reviews by sentiment. The same pattern scales directly to thousands of documents — just extend the request list.

import anthropic
import time

client = anthropic.Anthropic()

# Step 1: Build one request per document
requests = [
    {
        "custom_id": "review-001",
        "params": {
            "model": "claude-sonnet-4-5-20250929",
            "max_tokens": 10,
            "messages": [{
                "role": "user",
                "content": "Classify as positive/negative/neutral: 'Fast shipping, love it!'"
            }]
        }
    },
    {
        "custom_id": "review-002",
        "params": {
            "model": "claude-sonnet-4-5-20250929",
            "max_tokens": 10,
            "messages": [{
                "role": "user",
                "content": "Classify as positive/negative/neutral: 'Broke after one day.'"
            }]
        }
    }
]

# Step 2: Submit the batch
batch = client.messages.batches.create(requests=requests)
batch_id = batch.id
print(f"Batch submitted: {batch_id}")

# Step 3: Poll until complete
while True:
    status = client.messages.batches.retrieve(batch_id)
    if status.processing_status == "ended":
        break
    time.sleep(30)

# Step 4: Retrieve and match results
for result in client.messages.batches.results(batch_id):
    print(result.custom_id, result.result.message.content[0].text)

The output is a JSONL stream where each line pairs your custom_id with the model's response. For a document extraction job, you would parse the model's JSON output and insert the fields directly into your database.

How Do You Extract Structured Data from Documents at Scale?

For a workload like extracting revenue, net income, and fiscal quarter from thousands of earnings reports, the pattern is the same — but you gain an additional cost advantage. If many documents share a large system prompt or boilerplate legal text, you can add prompt caching on top of the batch discount. As the API reference confirms, the Batches API supports all standard Messages API features including vision, tool use, extended thinking, and prompt caching.

Combining batch pricing with prompt caching discounts on shared boilerplate text can reduce costs dramatically versus real-time extraction, while the async model means the pipeline runs overnight without blocking other work.

What Are the Most Common Pitfalls When Batch Processing Documents?

• Assuming results are in order. Results in the JSONL file are not guaranteed to match submission order. Always use the custom_id field to match each result back to its original request.
• Exceeding batch size limits. Each batch is limited to 100,000 requests or 256 MB, whichever is hit first. Exceeding the size limit returns an error. Chunk large datasets into multiple batch submissions and track each batch ID separately.
• Letting results expire. Results are available for 29 days from the batch creation timestamp, not from when processing ended. Download and archive results promptly.
• Skipping single-request validation. Validation errors on individual requests inside a batch can be hard to debug. Test your request shape with a single synchronous Messages API call before wrapping it in a batch submission.
• Not planning for the 24-hour window. Batches that do not finish within 24 hours expire. If you have more than 100,000 requests, split into multiple batches and monitor processing status in your pipeline.

How Does Batch Processing Compare to Other Claude API Approaches?

Is the 50% Cost Reduction Worth the Async Turnaround?

For any workload where an overnight or one-hour turnaround is acceptable, the answer is almost always yes. Consider a team running 2,000 evaluation test cases before a prompt deployment: running those synchronously would take many minutes and cost twice as much. Batching completes the suite asynchronously, integrates cleanly into CI/CD pipelines, and the custom_id maps directly back to your test case IDs for automated pass/fail analysis.

The discount also applies regardless of batch size — even a small batch of a few dozen documents gets the 50% reduction. And because the Batches API reached General Availability on the Anthropic API (graduating from public beta), it is production-ready for critical pipelines.

The only scenario where batch processing is the wrong choice is when your requests depend on each other — for example, a multi-turn conversation where each message depends on the previous response. In that case, sequential synchronous calls are the correct tool.