# List SMS messages (/api-reference/public-api/listSms)

`GET /v1/sms`

Base URL: `https://api.bitelio.com`

Your project's SMS history, newest first, **cursor-paginated** — the same shape as `GET /v1/emails`, so one client pages both the same way.

**Every row carries `segments` and `encoding`, and that is the point.** SMS is billed per segment: a GSM-7 message splits every 160 characters, a Unicode one every 70. A single accented character in a template flips the whole message to Unicode and can double its cost. This is the only place that number is readable after the send.

The body is not in the listing — it is on `GET /v1/sms/{id}`.

## Query parameters

- `limit`: integer — Page size.
- `cursor`: string — The previous page's `nextCursor`. Opaque — return it verbatim.
- `status`: enum ("PENDING" | "QUEUED" | "SENT" | "DELIVERED" | "UNDELIVERED" | "FAILED") — Filter by delivery status.
- `to`: string — Destination in E.164, matched exactly.
- `since`: string (date-time) — ISO 8601.
- `until`: string (date-time) — ISO 8601.

## Responses

### `200` — OK

- `data`: array<object>
  items:
    - `id`: string
    - `to`: string
    - `from`: string
    - `country`: string
    - `encoding`: enum ("GSM7" | "UCS2")
    - `segments`: integer
    - `status`: enum ("PENDING" | "QUEUED" | "SENT" | "DELIVERED" | "UNDELIVERED" | "FAILED")
    - `error`: string
- `nextCursor`: string

```json
{
  "data": [
    {
      "id": "string",
      "to": "string",
      "from": "string",
      "country": "string",
      "encoding": "GSM7",
      "segments": 0,
      "status": "PENDING",
      "error": "string"
    }
  ],
  "nextCursor": "string"
}
```

### `400` — Invalid limit, status or date

### `403` — The key lacks the sms:view scope

## Example request

```bash
curl -X GET 'https://api.bitelio.com/v1/sms' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```