Agent Number

GET /sms/messages

Read message history (sent + received), paginated

Description

Read-only paginated history across both inbound and outbound messages. Does **not** mutate `delivered_at` (use `/sms/receive` for that). Cursor-based keyset pagination — pass the previous response's `next_cursor` as `cursor` to fetch the next page.

Authentication

Bearer required. Send Authorization: Bearer <token>.

Code samples

Pick your runtime. Every sample is in the page source — switching tabs is for your eyes.

curl 'https://agentnumber.really.com/sms/messages?direction=both&since=<since>&until=<until>&limit=50&cursor=<cursor>' \
  --header 'Authorization: Bearer <your-token>'

Query parameters

NameTypeDescription
direction string Filter to one direction or the other. Default: both.
since string RFC3339 lower bound on `created_at` (inclusive).
until string RFC3339 upper bound on `created_at` (inclusive).
limit integer Max rows to return. Defaults to 50, capped at 100.
cursor string Opaque pagination token from a previous response's `next_cursor`.

Responses

200 Page of message history. `next_cursor` is `null` on the last page.

{
  "messages": [
    {
      "id": 4821,
      "direction": "received",
      "from_number": "+15555550199",
      "to_number": "+15555550123",
      "body": "Your code is 123456",
      "message_id": "msg_example_0000000000000000000000",
      "status": null,
      "created_at": "2026-04-30T18:24:01.000Z",
      "delivered_at": "2026-04-30T18:24:01.000Z"
    },
    {
      "id": 4820,
      "direction": "sent",
      "from_number": "+15555550123",
      "to_number": "+15555550199",
      "body": "Hello from my agent.",
      "message_id": "msg_01HM3PXJ4K8ZFQ5Y7B9W2N6V8Q",
      "status": "queued",
      "created_at": "2026-04-30T18:23:55.000Z",
      "delivered_at": null
    }
  ],
  "next_cursor": "4820|4810"
}

401 Missing, invalid, revoked, or expired bearer token.

{
  "error": "unauthorized",
  "message": "invalid, revoked, or expired token"
}