# Batches API

Canonical: https://tyxter.com/docs/api-reference/batches
Section: API reference

Create and inspect broadcast batches and failure exports.

# Batches API

Use POST /v1/batches to create a broadcast batch. Use GET /v1/batches, GET /v1/batches/{id}, pause/resume/cancel actions, and failure export endpoints to operate the batch lifecycle.

Before a batch is accepted, Tyxter resolves the approved TemplateVersion. Every inline recipient can satisfy modeled BODY requirements through variables in that binding's format: exact numeric keys for POSITIONAL or exact parameter-name keys for NAMED. A required text-HEADER or dynamic URL-button parameter has no batch request source, so it returns 400 template_param_mismatch with param template. The audience and audience_id shapes have no per-recipient variable source in either format and likewise cannot supply BODY, text-HEADER, or dynamic URL-button parameters, although template.header_media remains available for a modeled shared media header. A mismatch returns 400 template_param_mismatch with a corrective param such as recipients.0.variables, template.header_media, or template. No batch was accepted, billed, queued, or sent to Meta. A later approval change or unmodeled Meta behavior can still fail an accepted recipient asynchronously with the same code.

The create response carries a pacing forecast when Tyxter can make one: pacing.deferred_recipient_count is how many recipients are expected to wait for WhatsApp's daily NEW-recipient allowance on the sending number, and pacing.estimated_windows is roughly how many daily allowance windows the batch will span, counting the current one. A batch spanning more than one window is normal and is not an error — the waiting recipients stay queued and send by themselves as allowance frees up, and each one reports status_reason messaging_limit_pacing while it waits. Both numbers are ESTIMATES taken at accept: they move as other traffic on the same number consumes allowance, as recipients turn out to already be inside an open conversation window (those cost nothing), and as Meta raises or lowers the number's tier. There is deliberately no completion timestamp: the allowance window is a rolling one whose slots expire individually, so there is no single moment it resets and any timestamp would be read as a schedule.

pacing is null on GET /v1/batches/{id} and on GET /v1/batches. The forecast is an accept-time snapshot that Tyxter neither stores nor recomputes, so capture it from the create response. Null also means "no estimate" on the create response itself — the sending number could not be resolved, its allowance is not a finite number to divide by, or it has no finite cap at all — and it never means "no pacing". For live progress read enqueued_count and sent_count.