List batches
Query Parameters
Results are paged. When has_more is true, pass next_cursor from the response as cursor to fetch the next page.
- limitinteger
Default 25. Maximum 100.
- cursorstring
- statusscheduled, sending, paused, complete, canceled
Responses
- 200Page of Batch
Batches, newest first
- 401Error
Missing, malformed, or revoked API key
- 402Error
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
- 429Error
Rate limit or quota exceeded
Response Fields
The body is a page: data (the array), has_more, and next_cursor (null on the last page). Each item in data:
- idstring
Example:
bc_a1B2c3D4e5F6. - objectbatch
- namestring
- statusscheduled, sending, paused, complete, canceled
- fromstring
- bodystring
- sourceapi, csv, contacts
- testboolean
- scheduled_atstring (date-time)
Nullable.
- created_atstring (date-time)
- completed_atstring (date-time)
Nullable.
- countsobject
total = queued + sent + failed + opted_out + canceled, always. "sent" = accepted by the carrier; what happened next (delivered, failed, replies) is GET /v1/batches/{id}/results. "opted_out" also counts recipients unsubscribed from the batch topic.
- counts.totalinteger
- counts.queuedinteger
- counts.sentinteger
- counts.failedinteger
- counts.opted_outinteger
- counts.canceledinteger
- rejectedobject
Rows dropped at validation (not part of total), by reason. Nullable.
- variablesarray of string
- retriesinteger
Errors
Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.
- 401
Missing, malformed, or revoked API key
- 402
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
- 429
Rate limit or quota exceeded