List messages

Last updated Sep 20, 2026

GET /spools/{spool}/queues/{queue}/messages

One page of the queue's messages as they rest now, in send order, every state or one. Each entry describes a message without its payload; with handle=true it also carries a handle to the message's current delivery generation, which peek, recover and discard present back — a handle to a message that has since been delivered, settled, recovered or discarded answers 410, so a stale listing costs a fresh one and never an action on a delivery someone else took. A delayed message becoming visible keeps its handle. Ids identify and never act: no operation takes one. Responses carry Cache-Control no-store.

Sample

curl -X GET "$SPOOLER_API/spools/<spool>/queues/<queue>/messages" \
  -H "Authorization: Bearer $SPOOLER_KEY"

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
queue	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The queue name.
state	query	delayed / visible / pending / failed / unavailable	no	Keep only messages in this state; absent keeps every state.
limit	query	integer, 1–1,000, default 100	no	Max messages per page.
after	query	Cursor, 1–256 chars	no	Resume the listing just past this cursor (the previous page's next); absent starts at the first message.
handle	query	boolean	no	When true, every entry carries a handle. Off by default, since a handle is a bearer credential.

Responses

Status	Description
200	One page of messages.
400	The request is malformed; the kind names the problem.
401	The API key is missing or not recognized.
402	The account is suspended.
403	A plan limit refuses the operation; the kind names it.
404	The spool or queue does not exist; the kind says which.
429	The per-account request rate cap is exceeded; retry after the Retry-After delay.
503	The spool is momentarily unavailable.

200 headers

Header	Description
Cache-Control	Always no-store.

200 body shape

The shape, not a sample: values are the wire types; ? marks an optional field.

{
  // One page of the queue's messages, in send order.
  items: [
    {
      // The message's id.
      id: string,

      // The state the message rests in.
      state: "delayed" | "visible" | "pending" | "failed" | "unavailable",

      // Redeliveries so far.
      retries: integer,

      // When the message was sent (RFC 3339, UTC).
      createdAt: string,

      // When a delayed message becomes visible; present only in the
      // delayed state.
      visibleAt?: string,

      // When the current lease expires; present only in the pending state
      // on a queue with a lease timeout.
      leaseExpiresAt?: string,

      // When retention discards the message; absent when retention is
      // off.
      expiresAt?: string,

      // A handle to the message's current delivery generation; present
      // only when the listing asked for it via handle=true.
      //
      // Length:  16–128 chars
      // Pattern: ^[A-Za-z0-9_-]+$
      handle?: string,
    }
  ],

  // Cursor of the following page (pass as after); absent when this page
  // ends the listing.
  //
  // Length: 1–256 chars
  next?: string,
}

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted.