Skip to main content
GET
List messages
  • Credential: an API key, or a trial key, which lists only the messages of its trial.
  • Line-scoped keys: a line-scoped key gets only the messages of the lines of its list. A line_id outside the list returns an empty page.
  • Events: none.
  • Personal data: the items carry handles, message text, attachment file names and metadata. Request them only when needed, do not copy them into logs, tickets or other tools, and refer to a contact by an id of your own. See Personal data.
  • Pagination: a cursor, valid only with the sort, order and filters it was issued for. A cursor that cannot be read restarts the list from the first page, with 200. See Cursors.
  • Retention: a message is listed until iSnap deletes it, at least 72 hours after it recorded it. since and until bound that recording time: see Timestamps in queries.
  • Reaction entries: an item with kind: reaction does not say which message it reacts to. See Listing messages.
  • Rate limit: this operation and POST /v1/messages share the message-operations limit, 60 requests per rolling 60 seconds per network address, in addition to the request-rate limit: see Rate limits.

Errors

The errors that every operation shares are in Errors.

Authorizations

Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Query Parameters

line_id
string

Only the messages of this line (line_ followed by 25 letters or digits). A line that does not exist, or that is not a line of your account, gives an empty page.

Pattern: ^line_[0-9A-Za-z]{25}$
status
enum<string>

Only the messages with this status.

Available options:
queued,
scheduled,
sent,
delivered,
read,
failed,
cancelled
direction
enum<string>

outbound: only the messages the line sent. inbound: only the messages the line received.

Available options:
outbound,
inbound
since
string<date-time>

Inclusive lower bound on created_at: an ISO 8601 timestamp with a UTC offset, for example 2026-01-15T14:00:00Z.

until
string<date-time>

Inclusive upper bound on created_at: an ISO 8601 timestamp with a UTC offset, for example 2026-01-15T15:00:00Z.

kind
enum<string>

message leaves out voice notes and reaction entries. voice and reaction return only those. Omit it for all kinds.

Available options:
message,
voice,
reaction
sort
enum<string>
default:created_at

created_at, the default, orders by the time iSnap recorded each message. scheduled_for orders by planned departure, the value of the scheduled_for field: messages that have none, which are the inbound messages and the messages typed on the device of a line, come last in both directions.

Available options:
created_at,
scheduled_for
order
enum<string>

desc or asc. When omitted: desc for sort=created_at (newest first) and asc for sort=scheduled_for (soonest first).

Available options:
asc,
desc
cursor
string

The next_cursor of the previous page. Omit it for the first page. Send it with the same sort, order and filters as the request that returned it.

limit
integer
default:25

Number of messages per page, 1 to 100. The default is 25.

Required range: 1 <= x <= 100

Response

One page of messages.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

One page of messages.

trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.