Get a batch
const url = 'https://api.connect.ms/v2/sms/batches/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.connect.ms/v2/sms/batches/example \ --header 'Authorization: Bearer <token>'Returns one batch with its current status and message counts.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The id of the batch.
Header Parameters
Section titled “Header Parameters”The API version to use, for example 2026-10-01. Defaults to the version set on your API key.
Responses
Section titled “Responses”The batch.
A batch of SMS messages. The same shape is returned by every batch endpoint and carried by batch.* events.
object
The unique id of the batch.
How the batch was created: api (a list of messages), import (an uploaded file) or list (contact lists).
The batch status: queued (nothing has been sent yet), sending (some messages have been sent, failed or cancelled and the batch is not yet complete), paused (paced delivery paused or messages held for payment), completed or cancelled.
Message counts for the batch by status. sent includes delivered; total is every row including skipped ones.
object
Every row in the batch, including skipped ones.
Messages not yet handed to the network.
Messages handed to the network and not since failed, including those delivered.
Messages confirmed delivered.
Messages that failed.
Rows that were never queued; see skipped for why.
Messages that were cancelled.
Why rows were skipped rather than queued.
object
Recipients on the suppression list.
Recipients messaged within the skipMessagedWithinHours window.
Rows that failed validation.
Paced delivery details.
object
How many messages are sent per period.
The period a pacing rate applies to: hour or day.
Why paced delivery is paused: user (paused from the dashboard), sending_blocked (the workspace cannot send), sender_revoked (the sender is no longer approved), api_key_limit (the API key’s send limit was reached) or payment_required (the workspace is out of credit).
When (UTC) the last message is expected to send at the current rate, or null when not known.
Why a message is waiting rather than sending.
object
Why a message is being held: payment_required (the workspace is out of credit; the message sends once credit is restored or fails when its validity window passes).
When (UTC) the hold began.
When (UTC) the message fails if the hold is not lifted, or null when it has no validity window. Always null on a batch.
Rows that were rejected, by position. Only populated on the response that created the batch; empty everywhere else.
A row of the request that was not accepted.
object
The zero-based position of the row in the submitted messages.
What was wrong with the row.
The grouping tag applied to the batch, for usage reporting. A message can carry its own tag instead.
When (UTC) the batch was asked to send, or null when no send time was given.
When (UTC) the batch was created.
When (UTC) the last message reached a final state, or null while messages remain.
When (UTC) the batch was cancelled, or null.
Example
{ "source": "api", "status": "queued", "paced": { "period": "hour", "pauseReason": "user" }, "hold": { "reason": "payment_required" }}The request is not valid. The detail field says why, and errors lists any problems by field name.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The API key or bearer token is missing or not valid, or the request signature could not be verified.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The caller is not allowed to do this.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}No batch with that id.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The service is temporarily unavailable. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}