> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Messages
> List and filter sent messages, with cursor pagination and an updated_since reconciliation watermark.
Lists messages for the account the key belongs to. By default rows are returned newest-first for browsing. Pass `updated_since` to turn the endpoint into an incremental [reconciliation](/api-reference/v2/messages/reconciliation) feed.
## Query Parameters
Filter to one sending list by its ID.
Filter by sending-list phone number (E.164). Ignored when `sending_list_id` is set; an unmatched number returns zero rows.
Filter by recipient phone number (E.164).
One of `queued`, `sent`, `failed`, `dropped`, `orphaned`, `delivered`, `undelivered`.
Lower bound on `timestamp` (ISO-8601, **timezone-aware** — include `Z` or an offset). A naive datetime is rejected.
Upper bound on `timestamp` (ISO-8601, timezone-aware).
Reconciliation watermark (ISO-8601, timezone-aware). When set, returns rows with `updated_at` greater than this value, sorted oldest-change-first and keyset-paginated on `(updated_at, id)`. See [Reconciliation](/api-reference/v2/messages/reconciliation).
Scope results to an owned account (yourself or a child) carrying this external location ID. An unowned location returns an empty result, never another tenant's data.
Opaque pagination cursor from a previous response's `next_cursor`.
Page size, max 200.
## Response Fields
Array of message rows.
Opaque message ID (variable length).
Sending list number (E.164).
Recipient (E.164).
Message body.
Pipeline status.
Extra status context, if any.
SMS segments.
`GSM-7` or `UCS-2`.
The list this was sent from.
Send time (ISO-8601, UTC).
Last-change time (ISO-8601, UTC); the reconciliation watermark field.
Normalized delivery-receipt status.
Whether the delivery status is final.
Whether delivery is confirmed.
Carrier/pipeline error code, if failed.
Human-readable error, if failed.
Carrier-route message reference. Present only for providers whose IDs are globally unique; `null` otherwise.
ID of the linked inbound reply, if any.
When the recipient replied, if they did.
`estimated`, `settled`, `billed`, or `refunded`.
External IDs of the owning account (e.g. `external_location_id`).
`limit`, `has_more` (boolean), and `next_cursor` (opaque, `null` on the last page).
## Examples
```bash cURL theme={null}
curl -G https://api.tracklysms.com/api/v2/messages \
-H "X-Api-Key: trk_your_api_key" \
--data-urlencode "updated_since=2026-07-26T00:00:00Z" \
--data-urlencode "limit=200"
```
```python Python theme={null}
import requests
resp = requests.get(
"https://api.tracklysms.com/api/v2/messages",
headers={"X-Api-Key": "trk_your_api_key"},
params={"status": "delivered", "limit": 200},
)
data = resp.json()
for msg in data["messages"]:
print(msg["id"], msg["status"])
print("next:", data["pagination"]["next_cursor"])
```
```json Success (200) theme={null}
{
"messages": [
{
"id": "a1b2c3d4",
"from_number": "+18005551234",
"to_number": "+14155551234",
"body": "Hi",
"status": "delivered",
"status_detail": null,
"segment_count": 1,
"encoding": "GSM-7",
"sending_list_id": 88,
"timestamp": "2026-07-20T14:03:11.000000Z",
"updated_at": "2026-07-20T14:05:00.000000Z",
"dlr_status": "delivered",
"is_terminal": true,
"is_delivered": true,
"error_code": null,
"error_description": null,
"provider_message_id": "O3iFf1Eu",
"reply_id": null,
"replied_at": null,
"cost_state": "billed",
"external_ids": { "external_location_id": "loc_west" }
}
],
"pagination": { "limit": 200, "has_more": true, "next_cursor": "MjAyNi0wNy..." }
}
```
## Error Codes
| HTTP Status | Error Code | Description |
| ----------- | --------------- | ------------------------------------------------------------------------------- |
| 400 | `invalid_param` | A query parameter is malformed (e.g. a naive datetime, bad status, bad cursor). |
| 500 | `query_failed` | The query could not be executed (transient); retry. |
Also `401 invalid_credentials`.
## Next Steps
Keep a local mirror in sync with the watermark.
Fetch a single message by ID.