Describe a queue

Last updated Sep 17, 2026

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

The queue's settings and lifecycle state: the entry the listing carries for it, without paging through the listing. Counts are on the spool's stats, selected by queue.

Sample

curl -X GET "$SPOOLER_API/spools/<spool>/queues/<queue>" \
  -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.

Responses

Status	Description
200	The queue.
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 body shape

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

{
  // The queue's name.
  //
  // Length:  1–64 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 lands in the failure queue; 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.
    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,
    },
  },
}

429 headers

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