Skip to content
Home › Prompt Engineering & Structured Output

Message Batches API ⚠ verify

Prompt Engineering & Structured Output

Definition

An asynchronous API for processing large volumes of Messages requests at 50% cost savings, ideal for high-throughput, non-latency-sensitive workloads (batch extraction pipelines, monthly reports).

Key points

  • 50% cost savings vs real-time Messages API.
  • Limits: 100,000 requests OR 256 MB per batch (whichever first).
  • Timing: most batches finish <1h; 24h max processing window; results retained 29 days.
  • Each request needs a custom_id matching regex ^[a-zA-Z0-9_-]{1,64}$.
  • Not supported: streaming, Fast mode, Threads, max_tokens: 0. Not ZDR-eligible.
  • Use the 1-hour cache TTL with batches — the default 5-minute TTL expires before batch items run. Caching and batching combine — see Caching Plus Batching.
  • Routing rule (Architect's Playbook): "Never default to real-time for asynchronous needs." Urgent exceptions (<30m SLA) → real-time Messages API; standard/monthly workloads → Batch API; continuous arrival with a 30h SLA → submit batches every 6 hours.

Why it matters for the exam

  • 50% savings, the 100k/256MB limits, and the custom_id regex are precise, testable numbers.
  • The batch-vs-real-time SLA routing decision is a recurring cost-optimization scenario.

Common gotchas

  • Using the 5-minute cache TTL with batches wastes the cache — use ttl:'1h'.
  • Defaulting to the real-time Messages API for asynchronous / high-volume work is the anti-pattern.
  • Streaming and max_tokens: 0 do not work with batches.

See also

Sources

Referenced by