TextKitDocs

Cancel a batch

Cancels a scheduled batch, or stops a sending/paused one: every unsent message is canceled and counted.

POST/v1/batches/{id}/cancel

Path Parameters

  • idstringrequired

Details

If sweep_complete is false (very large batches), call again - it is idempotent.

Responses

  • 200Batch

    The updated batch, plus affected and sweep_complete

  • 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

  • 404Error

    Not found

  • 409Error

    Not allowed in the batch’s current status (or a retry is already running)

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • 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

  • 404

    Not found

  • 409

    Not allowed in the batch’s current status (or a retry is already running)

  • 429

    Rate limit or quota exceeded