---
title: "Get a send batch"
method: GET
path: "/api/v1/gateway/devices/{id}/sms-batch/{smsBatchId}"
tags: ["gateway"]
---

# Get a send batch

`GET /api/v1/gateway/devices/{id}/sms-batch/{smsBatchId}`

## Request

- Base URL: `https://api.textbee.dev`
- URL: `https://api.textbee.dev/api/v1/gateway/devices/{id}/sms-batch/{smsBatchId}`
- Auth: API key in header `x-api-key`

The batch returned by a send, plus one message per recipient. The batch status and counts are calculated from the messages, so they follow each status report from the phone. Poll this to see how a send is progressing.

## Path parameters

- `id` string, required
- `smsBatchId` string, required

## Response `200`

The batch and its messages.

- SMSBatchResponseDTO
  - `data` SMSBatchResultDTO, required
    - `batch` SMSBatchDTO, required
      - `_id` string, required: Batch id.
      - `user` string, required: Owner account id.
      - `message` string: Message text sent to every recipient in the batch.
      - `encrypted` boolean: Whether the body is end to end encrypted.
      - `recipientCount` number, required: Recipients in the batch.
      - `recipientPreview` string: Short preview of the recipient list.
      - `successCount` number, required: Messages the phone reported as sent or delivered. Equals sentCount plus deliveredCount.
      - `failureCount` number, required: Messages that failed, either on the phone or before they reached it.
      - `pendingCount` number: Messages not yet handed to the phone. Paced and scheduled messages wait here.
      - `dispatchedCount` number: Messages handed to the phone that have not reported a result yet.
      - `sentCount` number: Messages the phone sent that have no delivery report yet. A message moves to deliveredCount when its delivery report arrives.
      - `deliveredCount` number: Messages with a delivery report from the carrier.
      - `unknownCount` number: Messages with no result: no report from the phone 20 minutes after they were due, or a state textbee does not recognize. A late report still updates the message and the batch.
      - `status` 'pending' | 'processing' | 'completed' | 'partial_success' | 'failed' | 'unknown' | 'sent' | 'delivered', nullable: Outcome of the batch, calculated from its messages. processing: at least one message is pending or dispatched. completed: every message was sent or delivered. failed: every message failed. partial_success: some were sent or delivered, the rest failed or are unknown. unknown: none was sent and at least one is unknown, or the batch has no messages. pending: the batch was created and no message was queued yet. sent and delivered appear only on old batches that have no messages.
      - `error` string: Error from the last failed attempt to hand the batch to the phone. It can be present on a batch that later sent some messages.
      - `completedAt` string, date-time: When the batch reached its current final status. Absent while the batch is processing.
      - `statusCheckedAt` string, date-time: When the status and counts were last calculated from the messages.
      - `createdAt` string, date-time, required: When the batch was created.
      - `updatedAt` string, date-time, required: When the batch was last updated.
    - `messages` RetrieveSMSDTO[], required: Every message in the batch, one per recipient.
      - `_id` string, required: Message id.
      - `message` string: Message text. Empty when the message is end to end encrypted.
      - `device` MessageDeviceDTO, required
        - `_id` string, required: Device id.
        - `enabled` boolean, required: Whether the device may send and receive SMS.
        - `name` string: Your own label for the device.
        - `brand` string, required: Device brand.
        - `model` string, required: Device model.
        - `buildId` string, required: Android build id.
      - `type` 'SENT' | 'RECEIVED', required: Direction of the message, uppercase. Deprecated: read the lowercase direction field instead, whose values match the direction query filter.
      - `status` 'pending' | 'dispatched' | 'sent' | 'delivered' | 'failed' | 'unknown' | 'received', nullable: Delivery state, lowercase. Incoming messages are always received. Outgoing messages move from pending to sent, then to delivered when the carrier confirms. Absent on messages stored before status tracking, so treat a missing value as unknown.
      - `sender` string: Sender number. Set on received messages.
      - `recipient` string: Destination number. Set on sent messages.
      - `smsBatch` string: Id of the batch this message was sent in.
      - `encrypted` boolean: Whether the body is end to end encrypted. Encrypted bodies can only be read by your own client.
      - `simSubscriptionId` number: SIM requested for this send, as passed in the send request. Not necessarily the SIM used: read simUsed for that.
      - `simUsed` SimUsedDTO
        - `subscriptionId` number: Subscription id of the SIM.
        - `slotIndex` number: Zero-based slot of the SIM: 0 is SIM 1, 1 is SIM 2.
      - `receivedAt` string, date-time: When the message was received. Received messages only.
      - `requestedAt` string, date-time: When the send was requested. Sent messages only.
      - `dispatchDueAt` string, date-time: When the queue is due to hand the message to the push service. Set for queued messages that wait server-side before dispatch: scheduled sends, and large sends, which are released in waves paced to the device send delay so the phone is never asked to hold more than it can send. Absent for immediate sends.
      - `dispatchedAt` string, date-time: When the push service accepted the message for delivery to the device. Does not mean the device has received it; sentAt is the first device-confirmed timestamp.
      - `dispatchAttempts` number: How many times the message has been handed to the push service. Normally 1; higher when a message was dispatched again.
      - `pushReceivedAt` string, date-time: When the device received the push for this message. Absent for messages handled by app versions that do not report it.
      - `sendAttemptedAt` string, date-time: When the device handed the message to the radio. The gap to sentAt is time spent in the radio; the gap from pushReceivedAt is time the message waited on the device.
      - `sentAt` string, date-time: When the device reported the message as sent.
      - `deliveredAt` string, date-time: When the carrier confirmed delivery.
      - `failedAt` string, date-time: When the message failed.
      - `errorCode` string: Failure code reported by the device.
      - `errorMessage` string: Failure reason reported by the device.
      - `overLimit` boolean: True when the message was received while the account was over its plan limit. Received messages only. Absent otherwise.
      - `originalCreatedAt` string, date-time: When the platform stored the message. Set only on a received message uploaded more than 24 hours after receivedAt, whose createdAt is set to receivedAt.
      - `createdAt` string, date-time, required: When the record was created. For a received message uploaded more than 24 hours after receivedAt, this equals receivedAt and originalCreatedAt holds the upload time.
      - `updatedAt` string, date-time, required: When the record was last updated.

## Other responses

- `400`: The device id is not a valid id.
- `401`: Missing, invalid, or revoked API key.
- `404`: No such batch on this device.

---

[API](https://skmtc.dev/textbee/apis/textbee-api.md) · [All operations](https://skmtc.dev/textbee/apis/textbee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/textbee/apis/textbee-api/revisions/e720417e9514?raw)