Batch status

GET /api/messages/batch/{batch_id} - Aggregate status and members of a bulk send.

Endpoint

GET https://sms.esmsafrica.io/api/messages/batch/{batch_id}

{batch_id} is the batch_id returned by Send bulk. Returns status counts and total cost for the whole batch, plus a paginated list of its member messages.

Authentication

Authorization: Bearer esms_live_your_api_key

Query parameters

Parameter	Type	Description
`page`	integer	Zero-based page index (default `0`).
`limit`	integer	Members per page, `1`-`200` (default `50`).

Response

{
  "batch_id": "b6c2f1e0-1d2c-4a55-9b3f-8e6b0c2d4a11",
  "total": 2,
  "counts": {
    "delivered": 1,
    "submitted": 1
  },
  "cost": 0.0192,
  "page": 0,
  "limit": 50,
  "messages": [
    {
      "id": "msg_abc123",
      "phone": "+254712345678",
      "status": "delivered",
      "segments": 1,
      "cost": 0.0096,
      "error_code": null,
      "created_at": "2026-08-14T12:30:00+00:00",
      "delivered_at": "2026-08-14T12:30:04+00:00"
    }
  ]
}

Field	Description
`total`	Number of messages in the batch.
`counts`	Message count per status (`delivered`, `submitted`, `failed`, ...).
`cost`	Total wallet cost of the batch.
`messages[]`	Member messages for the requested page, newest first.

A batch with no messages (unknown batch_id) returns 404.

Example

curl https://sms.esmsafrica.io/api/messages/batch/b6c2f1e0-1d2c-4a55-9b3f-8e6b0c2d4a11 \
  -H "Authorization: Bearer esms_live_your_api_key"