openclaw-claude-batch

name	openclaw-claude-batch
description	Claude Batch API for processing large volumes of requests asynchronously with 50% cost savings. Use for bulk content generation, data analysis, content moderation, batch evaluations, or large-scale testing where immediate responses are not required.
metadata	{"openclaw":{"emoji":"🔄","requires":{"env":["ANTHROPIC_API_KEY"],"python":">=3.8"},"credentials":[{"name":"ANTHROPIC_API_KEY","description":"Anthropic API key for Claude Batch API access (sk-ant-...)","isRequired":true}]}}

Claude Batch API Skill

Process large volumes of Claude API requests asynchronously with 50% cost savings.

Quick Start

1. Prepare Requests (JSONL Format)

Create a request file where each line is a complete request:

import json

requests = [
    {
        "custom_id": "task-1",
        "params": {
            "model": "claude-opus-4-6",
            "max_tokens": 1024,
            "messages": [
                {"role": "user", "content": "Summarize this: ..."}
            ]
        }
    },
    {
        "custom_id": "task-2",
        "params": {
            "model": "claude-opus-4-6",
            "max_tokens": 1024,
            "messages": [
                {"role": "user", "content": "Analyze this: ..."}
            ]
        }
    }
]

with open("batch_requests.jsonl", "w") as f:
    for req in requests:
        f.write(json.dumps(req) + "\n")

2. Submit Batch

import anthropic

client = anthropic.Anthropic(api_key="your-api-key")

# Read requests from file
with open("batch_requests.jsonl") as f:
    requests = [json.loads(line) for line in f]

# Create batch
batch = client.messages.batches.create(requests=requests)
print(f"Batch created: {batch.id}")
print(f"Status: {batch.processing_status}")

3. Monitor & Retrieve Results

import time

# Poll for completion
while True:
    batch = client.messages.batches.retrieve(batch.id)
    print(f"Status: {batch.processing_status}")
    if batch.processing_status == "ended":
        break
    time.sleep(60)

# Stream results (memory-efficient)
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        print(f"{result.custom_id}: SUCCESS")
        print(result.result.message.content[0].text)
    elif result.result.type == "errored":
        print(f"{result.custom_id}: ERROR")
        print(result.result.error)

Key Concepts

Batch Limits

• Max 100,000 requests per batch OR 256 MB
• Processing: typically < 1 hour, max 24 hours
• Results available for 29 days after creation
• Order of results not guaranteed (use custom_id for matching)

Cost Savings

• 50% discount on all token usage
• Input tokens, output tokens, and cache usage all discounted
• Cache hits work on best-effort basis (30-98% typical)

Supported Features

✅ Vision, tool use, system messages, multi-turn conversations, prompt caching, all beta features ❌ Streaming (results polled instead)

Models

All active Claude models supported (Opus 4.6, Sonnet 4.6, Haiku 4.5, etc.)

Use Cases

Use Case	Why Batch API
Bulk content generation	1000s of product descriptions, summaries
Large-scale evaluations	Testing 1000s of test cases
Content moderation	Analyzing user-generated content at scale
Data analysis	Generating insights for large datasets
Bulk transformations	Converting, reformatting, or enhancing data

Workflow

1. Prepare - Build request list with unique custom_id for each
2. Submit - Create batch via API
3. Monitor - Poll status periodically (check every 60-120 seconds)
4. Process - Stream results efficiently from results_url
5. Handle Failures - Retry errored requests or proceed based on success rate

API Reference

For complete API documentation, request counts, error handling, and advanced features (prompt caching, cancellation), see references/api-overview.md.

For optimization strategies, troubleshooting, and production patterns, see references/best-practices.md.

Scripts

Ready-to-use Python scripts for common operations:

• scripts/batch_runner.py - Submit, monitor, cancel, and retrieve batch results
• scripts/batch_monitor.py - Real-time batch progress monitoring with adaptive polling
• scripts/build_batch.py - Build batch requests from CSV, JSON, text, or Python scripts

Pricing Example

Submitting 100,000 requests at ~1,000 tokens each:

• Standard API: $0.003 per request = $300
• Batch API: $0.0015 per request = $150 ✅ (50% savings)

Plus 1-hour cache: Additional 25% savings on cached content.