List queues

Last updated Oct 2, 2026

GET /spools/{spool}/queues

One name-ordered page of the spool's queues, each with its settings and lifecycle state; counts are on the spool's stats. Keyset pagination: a paged walk never duplicates or skips a queue that exists throughout it, but settings and membership may drift between pages.

Sample

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

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
limit	query	integer, 1–1,000, default 100	no	Max queues 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 queue.
match	query	string	no	Keep only queue names matching this RE2 regular expression, unanchored (anchor with ^ and $ for an exact match); absent lists everything. Pagination walks matching names only.

Responses

Status	Description
200	One page of the spool's queues.
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. A 403 without a kind, on any operation, means the API key is blocked.
404	The spool or queue does not exist; the kind says which.
429	The per-account request rate cap is exceeded. The body names the kind (rate_limited); the wait is the Retry-After header and is not repeated in the body. Headers are as structured as the body, and this one is the header HTTP defines for a wait.
503	The spool is momentarily unavailable.

200 body shape

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

{
  // One page of the spool's queues, ordered by name in byte order.
  items: [
    {
      // The queue's name.
      //
      // Length:  1–63 chars
      // Pattern: ^[A-Za-z0-9_:-]+$
      name: string,

      // The time of the queue creation; a recreation under the same name
      // gets a new one, so it identifies the queue across reuse of the
      // name.
      createdAt: string,

      // The queue's lifecycle state. draining refuses new messages and is
      // deleted once consumers empty it (failed messages block the drain
      // until discarded or recovered); deleting refuses all operations
      // while the deletion completes. Deleted queues leave the listing.
      state: "active" | "draining" | "deleting",

      // The queue's current settings, as applied.
      settings: {
        // Seconds before an unacked delivery is auto-nacked; 0 means the
        // timeout is disabled.
        leaseTimeoutSeconds: integer,

        // Redeliveries before a message is failed; 0 means no retries.
        maxRetries: integer,

        // Seconds a dedup key is remembered; 0 means dedup is disabled.
        dedupWindowSeconds: integer,

        // Seconds a message is kept before it is discarded, as set. At
        // least a minute today; 0 is reserved to mean no expiry, so treat
        // it as such.
        retentionSeconds: integer,

        // The retention actually enforced: retentionSeconds bounded by
        // the plan's retention limit. The clock starts when a message
        // first becomes visible (a send delay does not count) and keeps
        // running: a leased message is not expired while held, but nack,
        // release and a lease timeout return it with the clock as it was.
        // Failing restarts the clock, and so does recovering. A failed
        // message expires like any other.
        effectiveRetentionSeconds: integer,

        // The cap on the rate Recv hands out messages; all zero means no
        // limit.
        recvRateLimit: {
          // The token-bucket refill interval in microseconds; 0 means no
          // limit.
          intervalMicros: integer,

          // The bucket size; 0 means no limit.
          burst: integer,
        },
      },
    }
  ],

  // 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, whole and at least 1; always the delay-seconds form, never an HTTP-date.