Batches

Every send request creates a batch. For large sends (51 – 10,000 numbers) this is how you follow progress and get each message's ID.

GEThttps://api.cloudmetis.com/v1/sms/batches/{batch_id}scope: sms:read

Request

curl "https://api.cloudmetis.com/v1/sms/batches/bat_106?page=1&limit=100" \
  -H "Authorization: Bearer cm_live_your_key"

Query parameter	Default	Description
page	1	Page of messages to return
limit	100	Messages per page, up to 500

Response (200)

{
  "batch_id": "bat_106",
  "status": "completed",
  "recipients": 60,
  "processed": 60,
  "sent": 60,
  "delivered": 58,
  "failed": 2,
  "pending": 0,
  "created_at": "2026-11-01T14:29:30+03:00",
  "completed_at": "2026-11-01T14:29:32+03:00",
  "error": null,
  "sandbox": false,
  "messages": [
    {"message_id": "msg_187", "to": "+254712000201", "status": "delivered", "sms_parts": 1},
    {"message_id": "msg_188", "to": "+254712000202", "status": "delivered", "sms_parts": 1}
  ],
  "pagination": {"page": 1, "limit": 2, "total": 60, "total_pages": 30}
}

Field	Description
status	queued (waiting), processing (sending now), completed, or failed
recipients	Numbers to send to (after removing duplicates and opted-out numbers)
processed	Messages created so far — reaches recipients when sending finishes
sent, delivered, failed, pending	Counts, updated as delivery reports arrive
error	Why the batch failed, when status is failed
messages	This page of messages, oldest first

Counts keep changing after completed: completed means every message was handed to the network, while delivery reports can still arrive for a while.

Following a large send

1. Send the list and keep the batch_id from the 202 response.
2. Either receive webhooks for each message, or poll this endpoint every few seconds until status is completed.
3. Page through messages (up to 500 per page) to get every message_id.

Batches are processed in chunks of 500, so processed grows in steps on very large sends.

Errors

Status	Code	When
404	not_found	Unknown batch ID, or it belongs to another organisation
403	scope_denied	The key lacks sms:read