SMS Logs

SMS logging is essential for monitoring messaging activity, delivery tracking, and compliance requirements. On this page, we will dive into the SMS logging endpoints you can use to retrieve and analyze SMS records programmatically. We will look at how to fetch SMS logs with filtering, retrieve facet counts, and export records as CSV.

All SMS log endpoints are scoped to your customer account via the {customer_slug} path segment and authenticate with an API key created in the portal under Settings → API Keys. Send the key either as Authorization: Bearer xn_... or in the X-API-Key header. The key must include the tenant:usage-logs:read permission.

The SMS log model

The SMS log model contains the information returned for each SMS record: participants, message content, delivery timing, status, and cost. Phone numbers are stored as bare digits including the country code, with no leading + (e.g. 15551234567).

Properties

Name
sms_id
Type
uuid
Description
Unique identifier for the SMS log entry.
Name
number_id
Type
uuid
Description
Identifier of the xNumbers number associated with the message (nullable).
Name
direction
Type
string
Description
Message direction: "inbound" or "outbound".
Name
from_number
Type
string
Description
The originating phone number (digits with country code, no leading "+").
Name
to_number
Type
string
Description
The destination phone number (digits with country code, no leading "+").
Name
message
Type
string
Description
SMS message content (nullable).
Name
segments
Type
integer
Description
Number of SMS segments used.
Name
status
Type
string
Description
Delivery status: "sent", "delivered", "failed", or "pending".
Name
sent_at
Type
timestamp
Description
Message sent timestamp.
Name
delivered_at
Type
timestamp
Description
Message delivery timestamp (nullable).
Name
cost
Type
string
Description
Calculated cost for the message as a decimal string (nullable).
Name
currency
Type
string
Description
Currency for the cost (nullable).
Name
created_at
Type
timestamp
Description
Record creation timestamp.

GET/customers/{customer_slug}/logs/sms

List SMS logs

This endpoint allows you to retrieve SMS logs for your customer account with filtering and pagination. By default, a maximum of ten records are shown per page, ordered by sent_at.

Optional attributes

Name
page
Type
integer
Description
Page number for pagination (default: 1).
Name
limit
Type
integer
Description
Number of logs per page (default: 10).
Name
direction
Type
string
Description
Filter by message direction: "inbound" or "outbound". Multiple values can be passed comma-separated.
Name
status
Type
string
Description
Filter by delivery status: "sent", "delivered", "failed", or "pending". Multiple values can be passed comma-separated.
Name
country_code
Type
string
Description
Filter by country code — exactly 2 uppercase letters (e.g. "US").
Name
date_from
Type
string
Description
Only include messages with sent_at on or after this date (ISO 8601).
Name
date_to
Type
string
Description
Only include messages with sent_at on or before this date (ISO 8601).
Name
search
Type
string
Description
Partial match against from_number and to_number (max 100 characters).
Name
sort_by
Type
string
Description
Accepted values: "sent_at", "delivered_at", "segments", "cost", "created_at" (default: "sent_at"). Results are currently always ordered by sent_at.
Name
sort_order
Type
string
Description
Sort direction on sent_at: "asc" or "desc" (default: "desc").

Request

GET

/customers/{customer_slug}/logs/sms

curl -G https://api.xnumbers.io/api/customers/acme/logs/sms \
  -H "Authorization: Bearer xn_your_api_key" \
  -d page=1 \
  -d limit=10 \
  -d direction=outbound \
  -d date_from=2026-01-01 \
  -d sort_order=desc

Response

{
  "data": [
    {
      "sms_id": "12345678-1234-1234-1234-123456789abc",
      "number_id": "87654321-4321-4321-4321-210987654321",
      "direction": "outbound",
      "from_number": "12125551234",
      "to_number": "15559876543",
      "message": "Your verification code is: 123456",
      "segments": 1,
      "status": "delivered",
      "sent_at": "2026-01-15T10:30:00.000Z",
      "delivered_at": "2026-01-15T10:30:02.000Z",
      "cost": "0.0100",
      "currency": "USD",
      "created_at": "2026-01-15T10:30:03.000Z"
    }
  ],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 10,
    "totalPages": 25
  }
}

GET/customers/{customer_slug}/logs/sms/facets

This endpoint returns facet counts for your SMS logs — the number of logs grouped by status and by direction across your whole account. It takes no query parameters and is useful for building filter UIs or dashboards.

Request

GET

/customers/{customer_slug}/logs/sms/facets

curl https://api.xnumbers.io/api/customers/acme/logs/sms/facets \
  -H "Authorization: Bearer xn_your_api_key"

Response

{
  "status": {
    "delivered": 2310,
    "sent": 145,
    "failed": 27
  },
  "direction": {
    "inbound": 980,
    "outbound": 1502
  }
}

GET/customers/{customer_slug}/logs/sms/export/csv

Export SMS logs

This endpoint allows you to export SMS logs as a CSV file. It supports the same filter parameters as the list endpoint (direction, status, country_code, date_from, date_to, search). Pagination parameters are ignored — the export contains up to 10,000 records matching your filters, ordered by sent_at.

Export format

The CSV contains the columns: Sent Time, From Number, To Number, Segments, Status, Direction, Provider, Number Type, Cost, Currency, Tariff.

Request

GET

/customers/{customer_slug}/logs/sms/export/csv

curl -G https://api.xnumbers.io/api/customers/acme/logs/sms/export/csv \
  -H "Authorization: Bearer xn_your_api_key" \
  -d direction=outbound \
  -d date_from=2026-01-01 \
  -d date_to=2026-01-31 \
  --output sms-logs.csv

Returns the CSV file as a download with the headers:

Content-Type: text/csv
Content-Disposition: attachment; filename="{customer_slug}-sms-logs-export-YYYY-MM-DD.csv"

SMS Logs

The SMS log model

Properties

List SMS logs

Optional attributes

Request

Response

Retrieve SMS log facets

Request

Response

Export SMS logs

Export format

Request