Describe a queue

Last updated Oct 19, 2026

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

The queue's settings, lifecycle state and stats: the entry the listing carries for it, without paging through the listing.

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–63 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
queue	path	IdentName, 1–63 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; the kind is unauthenticated.
402	The account is suspended; the kind is account_suspended.
403	The operation is refused; the kind names why: a plan limit (queue_limit, retention_limit), or account_blocked on any operation when the account is on an abuse hold.
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.

{
  // The queue's name.
  //
  // Length:  1–63 chars
  // Pattern: ^[A-Za-z0-9_:-]+$
  name: string,

  // Unique to this queue: a queue created again under the same name gets
  // a new one. Present it back to act on this queue only, as a delete's
  // uid does.
  //
  // Length:  1–128 chars
  // Pattern: ^[A-Za-z0-9_-]+$
  uid: string,

  // The time of the queue creation.
  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,
    },
  },

  // The queue's message counts, from the same snapshot as the rest of the
  // entry; all zero on the queue a create returns.
  stats: {
    // When the counts were sampled. Equal values mean one snapshot.
    sampledAt: string,

    // When the cumulative counters started; they were zero at this
    // instant. It is the spool's last opening on its serving member, or
    // the queue's creation when the queue is newer than that. A restart
    // or failover moves it and starts the counters over from zero, so
    // compute rates only between samples with equal startedAt.
    startedAt: string,

    // Stored messages on the queue, every state counted. Can transiently
    // exceed the per-state sum: the difference is messages in transit
    // between states.
    total: integer,

    // The logical payload bytes of the counted messages.
    dataBytes: integer,

    // Scheduled for a future delivery time; not yet available to receive.
    delayed: integer,

    // Available to receive now.
    visible: integer,

    // Delivered and awaiting ack; auto-nacked back to visible when the
    // lease times out.
    pending: integer,

    // Failed: retries exhausted or failed explicitly, waiting for recover
    // or discard.
    failed: integer,

    // Held back because the service could not read their payload. No
    // delivery attempt is charged and no retry is consumed; the read is
    // retried automatically, so a non-zero count reflects a service-side
    // condition, not a consumer one.
    unavailable: integer,

    // Messages appended since startedAt; duplicates suppressed by dedup
    // are not counted. A cumulative counter: zero at startedAt and never
    // lowered until a restart or failover moves startedAt.
    addedTotal: integer,

    // Messages acked; same counter semantics as addedTotal.
    ackedTotal: integer,

    // Messages nacked; same counter semantics as addedTotal.
    nackedTotal: integer,

    // Deliveries released (returned without spending a retry); same
    // counter semantics as addedTotal.
    releasedTotal: integer,

    // Messages failed; same counter semantics as addedTotal.
    failedTotal: integer,

    // Messages explicitly discarded; same counter semantics as
    // addedTotal.
    discardedTotal: integer,

    // Messages discarded by retention; same counter semantics as
    // addedTotal. A growing rate means messages age out before consumers
    // reach them.
    expiredTotal: integer,
  },
}

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.