# List SMS delivery logs

Retrieve a paginated list of outbound notification SMS delivery logs for the organization.

Source: https://statusdashboard.com/docs/api/notifications/sms/list

`GET /app/notifications/sms/logs`

Returns a newest-first paginated list of SMS delivery log entries for notification-channel sends (event notifications and subscription verify/manage texts). Each entry records the provider handoff and any subsequent lifecycle events.

Requires the `admin` or `subscriber` role and the **SMS notifications** feature entitlement.

***

## Request
See [API Basics](/docs/api) for required headers.

### Query parameters
| Parameter   | Type    | Required | Description                                                                                             |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `limit`     | integer | No       | Max entries per page. Range: 1–100. Default: `10`.                                                      |
| `nextToken` | string  | No       | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination). |
| `recipient` | string  | No       | Filter logs to an exact E.164 phone number (e.g. `+14155552671`). Must be valid E.164 when provided.    |

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/notifications/sms/logs?recipient=%2B14155552671" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "logs": [
    {
      "logId": "019670ab-cdef-7234-b5f1-abc123def456",
      "sentAt": "2026-06-26T14:30:00.000Z",
      "recipient": "+14155552671",
      "sender": "sms-pool-id",
      "bodyPreview": "[Acme Corp] Investigating: API latency — https://status.acme.com/e/abc",
      "status": "delivered",
      "smsType": "event_notification",
      "messageId": "0100018abc1234-5678-90ab-cdef-EXAMPLE",
      "dashboardId": "550e8400-e29b-41d4-a716-446655440000",
      "dashboardName": "Acme Status",
      "eventId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "changeType": "created",
      "events": [
        { "type": "Accepted", "at": "2026-06-26T14:30:00.000Z" },
        { "type": "Send", "at": "2026-06-26T14:30:00.100Z" },
        { "type": "Delivery", "at": "2026-06-26T14:30:02.000Z" }
      ]
    }
  ],
  "nextToken": null
}
```

***

## Response fields
| Field       | Type           | Description                                                                         |
| ----------- | -------------- | ----------------------------------------------------------------------------------- |
| `logs`      | array          | Delivery log entries for this page, newest first.                                   |
| `nextToken` | string \| null | Next-page bookmark when more results exist. See [Pagination](/docs/api#pagination). |

### Log entry fields
Each `logs[]` item:

| Field               | Type              | Description                                                                                                          |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `logId`             | string            | Opaque unique identifier for the log entry.                                                                          |
| `sentAt`            | string            | ISO 8601 timestamp when the send was initiated.                                                                      |
| `recipient`         | string            | Recipient phone number in E.164 format.                                                                              |
| `sender`            | string            | Origination identity used for the send.                                                                              |
| `bodyPreview`       | string            | Truncated message body at send time.                                                                                 |
| `status`            | string            | Aggregate status: `submitted`, `sent`, `queued`, `pending`, `delivered`, `blocked`, `failed`, or `skipped`.          |
| `smsType`           | string            | `event_notification`, `subscription_verify`, or `subscription_manage`.                                               |
| `messageId`         | string \| omitted | Provider message ID after successful handoff.                                                                        |
| `dashboardId`       | string \| omitted | Dashboard UUID when applicable.                                                                                      |
| `dashboardName`     | string \| omitted | Dashboard display name when applicable.                                                                              |
| `eventId`           | string \| omitted | Event UUID for event notification SMS.                                                                               |
| `changeType`        | string \| omitted | Event notification change type (`created`, `updated`, `timeline`, `reopened`, `maintenance-advance`, `post-mortem`). |
| `events`            | array             | Chronological lifecycle events (see below).                                                                          |
| `failureReason`     | string \| omitted | Error summary when `status` is `failed`.                                                                             |
| `totalMessageParts` | number \| omitted | Message segment count when reported by the provider.                                                                 |

### Event object fields
| Field          | Type               | Description                                                              |
| -------------- | ------------------ | ------------------------------------------------------------------------ |
| `type`         | string             | Event type (`Accepted`, `Send`, `Delivery`, `Blocked`, `Skipped`, etc.). |
| `at`           | string             | ISO 8601 timestamp.                                                      |
| `detail`       | string \| omitted  | Short summary (e.g. block reason or provider detail).                    |
| `raw`          | string \| omitted  | Provider event JSON (diagnostics only).                                  |
| `rawBytes`     | number \| omitted  | Original byte length of `raw` before any truncation.                     |
| `rawTruncated` | boolean \| omitted | `true` when `raw` was truncated at 16 KB.                                |

### `skipped` status
When `status` is `skipped`, the recipient was on the organization's [suppression list](/docs/notifications/sms#suppression) list and the message was **not** handed to the messaging provider. These rows are written at send time and do not receive lifecycle events. Event notification SMS quota is not consumed; subscription verify/manage texts do not count toward the monthly SMS message quota in any case.

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

***

## Retention
Log entries are retained for **30 days** and then automatically deleted.

***

## Error responses
| Status | When                                                                                 |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | Invalid query parameters (e.g. malformed `recipient` or `nextToken`).                |
| `403`  | Missing required role, or the SMS notifications feature is not enabled on your plan. |