---
title: "List Batches"
method: GET
path: "/xms/v1/{service_plan_id}/batches"
tags: ["Batches"]
---

# List Batches

`GET /xms/v1/{service_plan_id}/batches`

With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination.

## Query parameters

- `page` integer
- `page_size` integer
- `start_date` string, date-time
- `end_date` string, date-time
- `from` string[]
- `client_reference` string

## Response `200`

OK. A successful response, or an [Error](https://developers.sinch.com/docs/sms/api-reference/status-codes).

- ApiBatchList
  - `count` integer — The total number of entries matching the given filters.
  - `page` integer — The requested page.
  - `batches` Batch[] — The page of batches matching the given filters.
    - union
      - TextResponse
        - `id` string — Unique identifier for batch
        - `to` MtDestination[] — List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
        - `from` string — Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.
        - `canceled` boolean — Indicates if the batch has been canceled or not.
        - `parameters` ParameterObj — Contains the parameters that will be used for customizing the message for each recipient. [Click here to learn more about parameterization](https://developers.sinch.com/docs/sms/resources/message-info/message-parameterization).
        - `body` string — The message content
        - `type` 'mt_text', required — Regular SMS
        - `created_at` string, date-time — Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `modified_at` string, date-time — Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `delivery_report` 'none' | 'summary' | 'full' | 'per_recipient' | 'per_recipient_final' — Kind of delivery report
        - `send_at` string, date-time — If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `expire_at` string, date-time — If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `callback_url` string — Override the default callback URL for this batch. Must be valid URL.
        - `client_reference` string — The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
        - `feedback_enabled` boolean — If set to `true`, then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery.
        - `flash_message` boolean — Shows message on screen without user interaction while not saving the message to the inbox.
        - `truncate_concat` boolean — If set to `true` the message will be shortened when exceeding one part.
        - `max_number_of_message_parts` integer — Message will be dispatched only if it is not split to more parts than Max Number of Message Parts
        - `from_ton` integer — The type of number for the sender number. Use to override the automatic detection.
        - `from_npi` integer — Number Plan Indicator for the sender number. Use to override the automatic detection.
      - BinaryResponse
        - `id` string — Unique identifier for batch.
        - `to` MtDestination[] — A list of phone numbers and group IDs that have received the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628).
        - `from` string — The sender number provided. Required if the Automatic Default Originator is not configured.
        - `canceled` boolean — Indicates whether or not the batch has been canceled.
        - `body` string — The message content provided. Base64 encoded.
        - `udh` string — The [UDH](https://community.sinch.com/t5/Glossary/UDH-User-Data-Header/ta-p/7776) header of a binary message HEX encoded. Max 140 bytes including the `body`.
        - `type` 'mt_binary', required — SMS in [binary](https://community.sinch.com/t5/Glossary/Binary-SMS/ta-p/7470) format.
        - `created_at` string, date-time — Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `modified_at` string, date-time — Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `delivery_report` 'none' | 'summary' | 'full' | 'per_recipient' | 'per_recipient_final' — Kind of delivery report
        - `send_at` string, date-time — If set, the date and time the message should be delivered. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `expire_at` string, date-time — If set, the date and time the message will expire. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - `callback_url` string — The callback URL provided in the request.
        - `client_reference` string — The string input to identify this batch message. If set, the identifier will be added in the delivery report/callback of this batch.
        - `feedback_enabled` boolean — If set to true, then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery.
        - `from_ton` integer — The type of number for the sender number.
        - `from_npi` integer — Number Plan Indicator for the sender number.
      - MediaResponse
        - `id` string — Unique identifier for batch
        - `to` MtDestination[] — List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
        - `from` string — Sender number. Required if Automatic Default Originator not configured.
        - `canceled` boolean — Indicates if the batch has been canceled or not.
        - `body` MediaBody — The message content, including a URL to the media file
          - `subject` string — The subject text
          - `message` string — The message text. Text only media messages will be rejected, please use SMS instead.
          - `url` string, required — URL to the media file
        - `parameters` ParameterObj — Contains the parameters that will be used for customizing the message for each recipient. [Click here to learn more about parameterization](https://developers.sinch.com/docs/sms/resources/message-info/message-parameterization).
        - `type` 'mt_media', required — Media message
        - `created_at` string, date-time — Timestamp for when batch was created. YYYY-MM-DDThh:mm:ss.SSSZ format
        - `modified_at` string, date-time — Timestamp for when batch was last updated. YYYY-MM-DDThh:mm:ss.SSSZ format
        - `delivery_report` 'none' | 'summary' | 'full' | 'per_recipient' | 'per_recipient_final' — Kind of delivery report
        - `send_at` string, date-time — If set in the future the message will be delayed until send_at occurs. Must be before `expire_at`. If set in the past messages will be sent immediately. YYYY-MM-DDThh:mm:ss.SSSZ format
        - `expire_at` string, date-time — If set the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after send_at. YYYY-MM-DDThh:mm:ss.SSSZ format
        - `callback_url` string — Override the default callback URL for this batch. Must be valid URL.
        - `client_reference` string — The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
        - `feedback_enabled` boolean — If set to true then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery.
        - `strict_validation` boolean — Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](https://developers.sinch.com/docs/mms/bestpractices/). If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.
  - `page_size` integer — The number of entries returned in this request.

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/sinch/apis/api-overview-sinch.md) · [All operations](https://skmtc.net/sinch/apis/api-overview-sinch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sinch/api-overview-sinch/revisions/67cb925f1c81/schema)