Batch Processing

The Message Batches API processes large volumes of requests at 50% of the standard API cost, with results delivered within 24 hours. This is the right tool for workloads that are high-volume but not time-sensitive: reviewing all 200 PRs merged last quarter, generating documentation for every module in a monorepo, analyzing a year of error logs for patterns, or running code quality checks across all repositories in an organization.

The batch workflow: construct an array of requests (each is a standard messages API call), submit the batch, and poll for completion. Results are returned as a downloadable JSONL file where each line is the response to one request. The 50% cost reduction makes batch processing economically viable for large-scale code analysis that would be prohibitively expensive at standard API rates.

// Submit a batch of code review requests
const batch = await client.messages.batches.create({
  requests: files.map((file, i) => ({
    custom_id: `review-${i}`,
    params: {
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{
        role: 'user',
        content: `Review this file for quality issues:\n${file.content}`,
      }],
    },
  })),
});

// Poll for completion
let status = await client.messages.batches.retrieve(batch.id);
while (status.processing_status === 'in_progress') {
  await new Promise(r => setTimeout(r, 60000)); // Check every minute
  status = await client.messages.batches.retrieve(batch.id);
}

// Download results
const results = await client.messages.batches.results(batch.id);